TexFiscal: emissão de NFS-e por API (2.0.0)

A ref vai na QUERY, não no corpo, e e a chave de idempotencia.

Toda recusa de validação acontece ANTES de reservar número de RPS. Número reservado e número consumido: validar depois deixaria buraco na numeracao, e buraco na numeracao o fisco cobra explicacao.

Se a nota estiver em processamento, a consulta PERGUNTA a prefeitura antes de responder: e por isso que consultar resolve e reenviar não.

Só nota autorizada cancela. 202 com processando_cancelamento quando a prefeitura não foi conclusiva: repita o DELETE ou consulte, o serviço confere e resolve.

Como a prefeitura devolveu. Exige token, e responde no-store: documento fiscal com CPF do tomador nunca entra em cache.

Gerado do XML autorizado. Exige token: não existe link público de documento fiscal aqui. Se você hoje entrega ao seu usuário o link do PDF do integrador, troque por um proxy autenticado no seu servidor.

Cobertura MEDIDA, não afirmada: cada município da lista teve o webservice da prefeitura consultado e o padrão conferido, e a resposta traz a data dessa verificação. Consulte antes de prometer emissão ao seu cliente.

Município ausente da lista não e necessariamente município impossível: e município que não verificamos ou que usa um provedor para o qual ainda não há driver. Pergunte.

Quantidade e valor por status no mês, no ambiente do token. O campo total soma TODOS os status, inclusive os que falharam, então ele não é o valor da fatura: quem responde por isso é cobravel, que aplica o mesmo critério do fechamento (nota que recebeu número da prefeitura, em produção). Em homologação cobravel é sempre 0, porque nada ali é cobrado.

Única rota sem token. Diz o mínimo de proposito: vigia não precisa de credencial, e o que não se responde não vaza.

Enviado por nós para a URL que você cadastrar, uma por ambiente.

Confira o X-TexFiscal-Assinatura antes de confiar no conteúdo: e o HMAC-SHA256 do CORPO CRU com o segredo do seu webhook. Compare com hash_equals ou equivalente, nunca com == .

Três regras do receptor, e a segunda já custou caro em outros integradores:

1. Responda 2xx rápido. Nosso timeout na tentativa imediata e 5 s.
2. DESCARTE evento fora de ordem. Uma entrega reagendada pode chegar DEPOIS de um evento mais novo da mesma ref: por exemplo, uma nfse_autorizada que falhou chegando depois da nfse_cancelada. Guarde o ocorrido_em do último evento aplicado por ref e ignore o que for mais antigo, senão você marca como autorizada uma nota que foi cancelada.
3. Trate entrega REPETIDA. Reenviamos até 16 vezes enquanto você não responder 2xx, e uma entrega pode chegar duas vezes se a sua resposta se perder. Deduplique pelo evento_id.