NFC-e

A NFC-e (modelo 65) é a nota do balcão. A API usa as mesmas regras da NF-e, com três diferenças: responde na hora, imprime em bobina e nunca deixa o caixa parado.

Resposta síncrona

POST /nfce espera a SEFAZ por até 20 segundos por padrão e devolve a nota já autorizada na maioria dos casos. Se a SEFAZ não responder a tempo e a contingência automática estiver ligada no emitente, a nota sai em contingencia — pronta para imprimir — e é transmitida depois.

POST /nfce

curl -X POST "$MADNOTAS_URL/nfce" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d @venda.json

venda.json (dados fictícios)

{
    "ref": "caixa-3-cupom-88",
    "itens": [
        {
            "codigo": "CAFE01",
            "descricao": "CAFE ESPRESSO",
            "ncm": "21011110",
            "cfop": "5102",
            "unidade": "UN",
            "quantidade": "2",
            "valor_unitario": "6.50",
            "valor_bruto": "13.00",
            "icms": {
                "origem": "0",
                "csosn": "102"
            },
            "pis": {
                "cst": "07"
            },
            "cofins": {
                "cst": "07"
            }
        }
    ],
    "pagamentos": [
        {
            "forma": "dinheiro",
            "valor": "20.00"
        }
    ],
    "troco": "7.00"
}

Sem destinatário, a NFC-e sai para consumidor não identificado. O troco é a diferença entre o que o cliente pagou e o total.

Consumidor

O destinatário é opcional até o valor-limite definido pela UF; acima dele, informe CPF ou CNPJ. A validação avisa antes do envio.

Pagamento

Na NFC-e, pagamentos é obrigatório: informe ao menos uma forma (pix, dinheiro, cartao_credito…) com o valor. Sem a lista, ou com ela vazia, a resposta é 422 com pagamentos_obrigatorio no campo pagamentos: na NFC-e a MadNotas não completa “sem pagamento” por você.

CSC e QR Code

Cadastre o CSC e o identificador (PUT /emitentes/{id}/csc, um por ambiente). A MadNotas gera o QR Code e a URL de consulta da UF; você não precisa calcular nada.

Impressão

Rota	Saída
`GET /nfce/{id}/danfce?largura=80`	PDF para bobina de 80 mm
`GET /nfce/{id}/danfce?largura=58`	PDF para bobina de 58 mm
`GET /nfce/{id}/escpos`	Comandos ESC/POS prontos para enviar à impressora térmica

Contingência offline

Na contingência, a NFC-e é assinada e impressa sem a autorização, com a mensagem de contingência no DANFCE. A MadNotas transmite assim que a SEFAZ volta e avisa o resultado pelo webhook nfce.autorizada ou nfce.rejeitada. Detalhes no guia de contingência.

Cancelamento

O prazo de cancelamento da NFC-e é curto e varia por UF (em geral 30 minutos). POST /nfce/{id}/cancelamento recusa com mensagem clara quando o prazo passou. NFC-e não tem carta de correção.