API de nota fiscal: a requisição, a resposta e o que acontece quando dá errado

A chamada que emite, e o que volta:

É uma API REST, com autenticação HTTP Basic: o token vai no usuário e a senha fica vazia. São dois ambientes, cada um com o seu token, e o token de um apresentado no outro recebe 401. A homologação fala com o ambiente de teste da prefeitura, é ilimitada e não tem custo.

A referência da sua transação vai na consulta da URL. Ela é a chave de idempotência, e é o campo mais importante desta página inteira.

curl -u "SEU_TOKEN:" \
     -H "Content-Type: application/json" \
     -X POST "https://homologacao-nfse.texfiscal.com.br/v2/nfse?ref=venda-000123" \
     -d '{
  "data_emissao": "2026-10-01T10:00:00",
  "tomador": {
    "cpf": "52998224725",
    "razao_social": "Maria de Assuncao Silva",
    "email": "maria@exemplo.com",
    "endereco": {
      "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
      "codigo_municipio": "2910800", "uf": "BA", "cep": "44001000"
    }
  },
  "servico": {
    "valor_servicos": 150.00,
    "aliquota": 2.00,
    "iss_retido": false,
    "item_lista_servico": "4.10",
    "discriminacao": "Consulta nutricional mensal."
  }
}'

{
  "ref": "venda-000123",
  "status": "autorizado",
  "numero": "1037",
  "numero_rps": "412",
  "serie_rps": "1",
  "codigo_verificacao": "QX7M-2K9P",
  "data_emissao": "2026-10-01T10:00:04-03:00",
  "url": "https://nfse.texfiscal.com.br/v2/nfse/venda-000123/pdf",
  "caminho_xml_nota_fiscal": "/v2/nfse/venda-000123/xml"
}

A regra que evita o pior defeito: uma venda, uma nota

Repetir a chamada com a mesma referência não emite de novo: devolve a nota que já existe. É isso que torna seguro o reenvio depois de um tempo esgotado, e é por isso que a referência precisa sair da sua transação, nunca de relógio e nunca de valor aleatório.

Três detalhes que já custaram documento duplicado em integrações alheias:

• Maiúscula conta. As referências ped-1 e PED-1 são duas notas, ou seja, dois documentos fiscais para a mesma venda. Derive sempre da mesma forma.
• HTTP 202 não é falha. Significa que a nota está em processamento na prefeitura. Reenviar duplica documento fiscal. Só a consulta resolve, ou o aviso do webhook.
• Referência de nota cancelada não volta. Ela responde 409, porque a nota cancelada continua existindo como documento fiscal. A substituta usa uma referência nova.

Quando a resposta se perde no caminho, o tempo esgota ou o seu cliente devolve HTTP zero, o desfecho é desconhecido, nunca rejeição. A regra é esta: grave a referência antes de chamar; consulte antes de qualquer reenvio; e trate como pendente o que a consulta também não responder, repetindo em minutos.

Os erros que você precisa tratar:

Trate sempre pelo campo de código, nunca pelo texto da mensagem, que pode melhorar sem aviso. Código que você não reconhece se trata pelo status HTTP: 4xx é problema no pedido ou no cadastro e repetir igual não adianta; 5xx é nosso.

Existe uma rota que valida sem emitir: ela devolve os mesmos erros da emissão, sem consumir numeração, sem falar com a prefeitura e sem exigir certificado. É o caminho para homologar a integração enquanto o certificado digital do cliente ainda não chegou.

POST /v2/nfse/validar          200 {"status":"valido"}
                               422 {"codigo":"requisicao_invalida","erros":[...]}

Vale igual para /v2/nfe/validar e /v2/nfce/validar.

PDF, XML e o link que o seu cliente abre sem token:

O documento autorizado volta em dois formatos, os dois atrás do seu token. O PDF nunca deve ser colado num e-mail ao cliente final: ele receberia 401 em JSON e ainda veria o endereço da sua API fiscal. Aconteceu com um integrador em 17/09/2026.

Para entregar ao destinatário da nota existe um endereço assinado, de validade curta, que abre o documento sem token. O padrão é 15 minutos e o teto é sete dias. Quem tiver o endereço abre aquele documento até ele expirar, então ele vai para o destinatário da nota e para mais ninguém. É melhor do que escrever um intermediário autenticado no seu servidor.

A nota autorizada, o PDF e o XML ficam guardados por cinco anos.

GET /v2/nfse/venda-000123            estado atual (consulta à prefeitura se pendente)
GET /v2/nfse/venda-000123/xml        XML autorizado, como a prefeitura devolveu
GET /v2/nfse/venda-000123/pdf        DANFSe, exige o seu token
GET /v2/nfse/venda-000123/pdf/link   {"url": "..."} de validade curta, sem token
     ?validade=<segundos>            padrão 900, teto 604800 (sete dias)

GET /v2/nfse?de=2026-10-01&ate=2026-10-31&status=autorizado&pagina=1
     listagem paginada, 50 por página, para conciliar sem consultar uma a uma
DELETE /v2/nfse/venda-000123         {"justificativa": "...", "motivo": 1}

Webhook: o aviso, e as três regras do receptor:

Você cadastra um endereço por ambiente. A cada desfecho o serviço faz uma chamada nele com o mesmo corpo da consulta, mais o nome do evento e a referência. Vão junto o identificador do evento, o número da tentativa e a assinatura, que é um HMAC-SHA256 do corpo cru com o segredo do seu webhook. Confira a assinatura com comparação de tempo constante, nunca com igualdade simples.

As três regras do receptor, e a segunda já causou prejuízo em outras integrações:

1. Responda rápido. A primeira tentativa espera 5 segundos; as reentregas agendadas esperam 20. Faça o trabalho pesado depois de responder.
2. Descarte evento fora de ordem. Uma entrega que falhou e foi reagendada pode chegar depois de um evento mais novo da mesma referência. Guarde o instante do último evento aplicado e ignore o que for mais antigo, senão você marca como autorizada uma nota cancelada.
3. Trate entrega repetida. Reenviamos com recuo crescente, de 1, 5, 15, 60 e 360 minutos, até 16 tentativas, por até três dias. Use o identificador do evento, que é único e estável, como chave de deduplicação.

Não cadastrar webhook é uma escolha válida: nesse caso, consulte. Mas não consulte em laço apertado, porque cada consulta de nota pendente pergunta à prefeitura. Espere 2 segundos, depois 4, 8, 16, até 60, e pare de consultar depois de cinco minutos: o serviço resolve sozinho.

Mercadoria: NF-e e NFC-e, com a ressalva que importa:

Além da nota de serviço municipal, a API emite NF-e modelo 55 e NFC-e modelo 65 direto na SEFAZ, com a mesma referência, a mesma idempotência e os mesmos literais de estado. Há carta de correção para a NF-e, inutilização de faixa de numeração, consulta por número e por chave de acesso, e o conteúdo exato do QR Code do cupom.

A ressalva, que vem antes de qualquer decisão: o emissor precisa estar habilitado para isso, e hoje a cobertura de mercadoria é a Bahia, com a NF-e na SEFAZ-BA e a NFC-e na SVRS. Emissor não habilitado recebe 422, e UF fora da cobertura também. Se o seu caso é mercadoria fora da Bahia, fale com a gente antes de decidir, em vez de descobrir depois de integrar.

Um comportamento próprio da mercadoria vale conhecer: a SEFAZ pode DENEGAR o uso do número. É estado final, o número foi consumido e não volta, o XML denegado continua disponível, e reemitir a mesma referência responde 409. Nesse caso a saída é emitir com outro número.

O que este serviço nunca faz:

• Nunca responde 502, 503 ou 504 em rota de API. Falha de dependência sai como 422 com corpo próprio. A razão é prática: a borda da Cloudflare troca o corpo de 5xx pela página de erro dela, e a sua chamada cairia no tratamento de exceção como erro de rede genérico, sem mensagem.
• Nunca reenvia sozinho uma nota sem resposta conclusiva.
• Nunca corta nem arruma dado fiscal em silêncio. O que passa do limite do padrão é recusado com mensagem e correção, porque cortar um nome ou arredondar um valor produz uma nota diferente da que o cliente pediu, e ele só descobre na apuração.
• Nunca guarda o seu token em claro nem o certificado fora do cofre.
• Nunca entrega PDF ou XML por endereço público sem validade.

O contrato inteiro é público: OpenAPI 3.1, coleção do Postman, o guia de integração em texto e a lista de cidades atendidas. Tudo sem token, para você avaliar antes de criar conta.