API de NFS-e — Ext Contabilidade

O reference que você enviou na emissão. Obrigatório — esta rota é busca por referência, não listagem: sem ele a resposta é 400 invalid_request.

Como reference é único por empresa dentro de cada modo, o resultado tem no máximo uma nota. Sem resultado, é 200 com data vazio.

Chave escolhida por você para tornar a emissão segura de repetir. Opcional, e altamente recomendada em qualquer cliente com retry automático. Use uma chave nova por nota.

• Mesmo corpo + mesma chave devolve a primeira resposta, sem emitir de novo — é o que torna o retry de rede seguro.
• Corpo diferente com a mesma chave é 409 idempotency_key_reuse, por toda a janela de 24h: a chave identifica UMA emissão.
• Mesmo corpo, primeira ainda em voo, é 409 idempotency_key_in_use, que é repetível: aguarde e consulte antes de reenviar.
• Janela de 24h. Passada, a chave é esquecida e o mesmo corpo emite uma segunda nota.

Sem o header não há replay. A API ainda barra duplicata evidente — mesmo valor e mesma descrição em menos de um minuto — com 409 duplicate_suspected, mas essa rede é frouxa: não pega o retry que chega depois do minuto nem duas chamadas simultâneas, e recusa duas notas legitimamente iguais no mesmo minuto.

Melhor ainda: mande reference. É a única proteção que não expira — sendo único por empresa, a segunda emissão com a mesma referência é 409 nfse.reference_in_use, trazendo o id da original. Os dois se somam: a Idempotency-Key REPETE a resposta no retry imediato; o reference RECUSA a segunda nota para sempre.

Valor total do serviço em centavos, inteiro. R$ 1.250,50 se envia como 125050 — nunca 1250.50, que é recusado com 400 em vez de virar R$ 12,50 em silêncio. Mínimo 100 (R$ 1,00), máximo 9007199254740991. É o valor que vai para a nota, sem retenções.

Descrição do serviço, impressa na nota. Entre 1 e 2000 caracteres — o teto é da nota fiscal, não nosso.

Sai como enviado, com UMA exceção: os marcadores {{data}}, {{mes}}, {{mes_extenso}}, {{mes_anterior}}, {{mes_anterior_extenso}} e {{ano}} são substituídos na emissão, resolvidos na data em que a chamada é recebida. Texto sem {{ passa intacto.

Tomador do serviço. Omitir o objeto inteiro emite uma nota sem tomador, que é válida.

Alguns municípios exigem o tomador: neles, a nota sem customer.document é recusada na hora com 422 nfse.customer_required, antes do 202. Nos demais, nota sem tomador passa normalmente.

Tomador no exterior é exportação de serviço, e sai por aqui: mande customer.type: "foreign" com customer.address completo, a identificação fiscal (customer.tax_id ou customer.tax_id_absence_reason) e foreign_amount. Sem o type, o tomador é tratado como brasileiro — omitir customer continua significando *nota sem tomador*, e não *tomador no exterior*.

Onde está o tomador. br (padrão) é o comportamento de sempre — identificação por CPF/CNPJ, operação doméstica tributável. foreign faz a nota sair como exportação de serviço: sem ISS, com o grupo de comércio exterior, e exigindo customer.address completo, customer.tax_id (ou customer.tax_id_absence_reason) e foreign_amount.

Omitir o campo é o mesmo que br. Nenhum payload que funciona hoje muda de comportamento.

CPF (11 dígitos) ou CNPJ (14), apenas dígitos — máscara com pontos, barra ou traço é RECUSADA com 400, não limpa.

Nome do tomador. Obrigatório quando customer.document é um CPF — o nome é impresso na nota, não há cadastro público de nome de pessoa física, e sem ele a nota é 422 nfse.customer_name_required. Em CNPJ é opcional: vence o nome do cadastro da Receita, e este campo é o fallback se a consulta não resolver.

Número de identificação fiscal do tomador no país dele (NIF). Exportação exige este campo ou customer.tax_id_absence_reason — nunca os dois vazios.

Motivo de o tomador não ter identificação fiscal informada. exempt = dispensado; not_required = não exigência no país dele. Use quando não houver customer.tax_id.

Endereço do tomador no exterior, completo. Obrigatório quando customer.type é foreign, e recusado quando é br — no caminho doméstico o endereço vem do cadastro da Receita, não do payload.

Logradouro do tomador no exterior (xLgr da DPS).

Número do endereço (nro da DPS).

Bairro ou distrito (xBairro da DPS). Obrigatório pelo leiaute, mesmo onde o endereço local não usa bairro.

Cidade (xCidade da DPS).

Estado, província ou região (xEstProvReg da DPS). Texto livre — não é a sigla de UF brasileira.

Código postal no formato do país de destino (cEndPost da DPS). Formato livre: não é validado como CEP brasileiro.

País do tomador em ISO 3166-1 alpha-2 — dois caracteres, como US, PT ou MZ. Vai para endExt/cPais e para tribMun/cPaisResult, o país em que o resultado do serviço se verifica. BR não é aceito: nota com tomador no Brasil não é exportação.

Valor da nota na moeda do faturamento. Obrigatório quando customer.type é foreign; recusado fora da exportação.

Não substitui amount_in_cents. Os dois são exigidos: o valor em reais é o que vai para a nota e para a apuração, e a API não converte câmbio — a taxa é decisão sua.

Sigla ISO de três letras da moeda do faturamento — USD, EUR, GBP. Não é o código numérico do BACEN: a tradução é nossa. Moeda fora da lista aceita é 422 nfse.currency_unsupported, com as siglas no corpo do erro.

Valor na moeda estrangeira em centavos, número inteiro. 3.600,00 se envia como 360000.

Duas casas decimais para qualquer moeda, inclusive as que não têm centavo (iene) ou têm três casas (dinar kuwaitiano): é o que a DPS recebe, e prometer outra precisão seria prometer o que a emissão não carrega.

Seu identificador para esta nota — tipicamente o id da fatura no seu sistema. Opcional, e a forma mais confiável de reencontrar a nota: o id que devolvemos se perde se o seu processo morrer antes de gravá-lo, e a Idempotency-Key é esquecida em 24h.

• Único por empresa, dentro de cada modo. Reenviar o mesmo é 409 nfse.reference_in_use, com o id da nota que já existe na mensagem — o retry nunca vira nota duplicada, sem prazo de validade. Precisando de duas notas para a mesma fatura, use referências diferentes.
• A mesma referência serve uma vez em teste e uma em produção: os modos não se enxergam.
• Consultável em GET /v1/nfse?reference=....
• Até 64 caracteres, sem espaços — espaço é recusado em vez de aparado, porque "INV-1 " e "INV-1" seriam chaves diferentes.

Com Idempotency-Key junto, os dois se somam: o retry imediato ganha o REPLAY da chave, e só uma referência de verdade repetida cai no 409.

CNAE em que a nota deve sair, 7 dígitos, apenas números (a máscara 6202-3/00 é recusada com 400). Opcional.

• Omitido, a nota sai na atividade principal — o certo para a maioria.
• Enviado, precisa estar no cadastro da empresa na Receita Federal, principal ou secundária; um que não esteja é 422 nfse.cnae_not_allowed.
• A nota sai na linha padrão daquele CNAE; precisando de outra, mande service_code junto. CNAE sem linha padrão é 422 nfse.cnae_without_default.

O cnae e o service_code da resposta confirmam a linha em que a nota saiu.

Código de tributação nacional da linha, 6 dígitos, apenas números. Opcional, e o desempate do cnae — não confunda os dois: aqui são 6 dígitos (010501), não os 7 do CNAE.

A linha da nota sai desta tabela:

Mande o par quando o seu CNAE tiver mais de uma linha e você precisar da que não é a padrão. Código fora do catálogo é 422 nfse.service_code_unknown; código que existe mas não é da empresa, 422 nfse.service_code_not_allowed.

Id da nota, com ou sem o prefixo nfse_. O UUID cru funciona; um prefixo de outro tipo de recurso é 400, não 404.

Motivo do cancelamento, registrado no evento fiscal. Omitido, assume other.

Justificativa livre, de 15 a 255 caracteres — o limite é da nota fiscal, não nosso, e fora dele o cancelamento é recusado. Validamos aqui para a recusa chegar na hora, e não minutos depois com a nota presa. Omitida, usamos uma padrão.

Id da nota, com ou sem o prefixo nfse_. O UUID cru funciona; um prefixo de outro tipo de recurso é 400, não 404.

Id da nota, com ou sem o prefixo nfse_. O UUID cru funciona; um prefixo de outro tipo de recurso é 400, não 404.

Id da nota, com ou sem o prefixo nfse_. O UUID cru funciona; um prefixo de outro tipo de recurso é 400, não 404.