API de NFS-e: emissão, consulta e cancelamento pelo seu sistema
Troque a URL base e o token: o resto do seu código continua igual. O TexFiscal responde no mesmo contrato REST v2 que o seu sistema já usa, com caminhos, campos e literais de status idênticos.
O que a migração exige, item por item
Trocar de emissor normalmente significa reescrever o cliente: outro formato de payload, outros nomes de campo, outro vocabulário de status, outro fluxo de erro. É por isso que integração fiscal vira dependência difícil de largar. O TexFiscal nasceu falando o contrato REST v2 exatamente para tirar esse custo do caminho.
| O que a troca costuma exigir | Trocando por outro fornecedor | Trocando para o TexFiscal |
|---|---|---|
| Reescrever o cliente HTTP | Sim: outro payload e outros nomes de campo | Não: mesmos caminhos e campos |
| Reescrever o tratamento de status | Sim: outro vocabulário | Não: autorizado, processando_autorizacao, erro_autorizacao, cancelado |
| Refazer a idempotência | Sim, e é onde nasce nota duplicada | Não: a mesma ref na query, com o mesmo significado |
| Refazer o receptor de webhook | Sim | Não: o mesmo X-Webhook-Token, mais uma assinatura HMAC opcional |
| Plano de volta se der errado | Outra migração inteira | Apagar duas linhas do .env e reiniciar |
O rollback é o ponto que mais convence quem já se queimou: enquanto o contrato for o mesmo, voltar atrás custa segundos, não um projeto. Recomendamos manter os dois lados vivos por 30 dias antes de cancelar o contrato antigo.
85 cidades, verificadas uma a uma, com a data no ar
É comum ver número de cobertura em página de vendas sem dizer quando aquilo foi conferido. Número sem data não é informação, é propaganda, e quem integra só descobre a verdade no dia em que a nota do cliente dele não sai. Aqui cada cidade da lista teve o webservice da prefeitura consultado de verdade, e o contrato comparado com o do município onde o emissor está homologado. Confira agora:
Cidades atendidasVerificação de 02/09/2026
Cidade fora da lista não é cidade impossível: é cidade que ainda não verificamos, ou que usa um provedor para o qual ainda não escrevemos o driver. Pergunte antes de decidir. O que não fazemos é prometer cobertura que não medimos.
O contrato inteiro publicado, para você e para o seu assistente
Hoje boa parte das integrações é escrita com um assistente de IA ao lado. Assistente sem contrato declarado adivinha nome de campo, e o que ele adivinha errado vira nota recusada pela prefeitura, com numeração de RPS consumida. Por isso o contrato do TexFiscal é público, sem token, e é gerado de uma fonte só: mudar a API sem regerar o contrato reprova na nossa bancada antes de publicar.
llms.txt
Índice curto no formato que os assistentes leem primeiro, com as três regras que evitam
quase todo erro de integração: a ref idempotente, a nota em processamento
que nunca se reenvia, e a alíquota em percentual.
OpenAPI 3.1
Definição completa: rotas, esquemas, limites de cada campo, catálogo de códigos de erro com exemplo de corpo. Serve para gerar cliente com o OpenAPI Generator, importar a coleção pronta no Postman e alimentar o assistente sem ambiguidade.
Documentação navegável openapi.json Coleção do Postmanllms-full.txt
O guia inteiro embutido, o mesmo texto que uma pessoa lê. Guia para máquina e guia para gente que divergem produzem integração que passa no seu teste e falha na prefeitura.
nfse.seusaude.com/llms-full.txtO que você não precisa construir
Seis peças que todo integrador de nota fiscal acaba escrevendo, e que aqui já vêm prontas e cobertas por teste.
Idempotência que segura de verdade
A ref é a chave da sua transação. Duas chamadas concorrentes com a mesma
ref não geram duas notas: quem perde a corrida recebe a nota de quem ganhou.
Recusa antes de consumir numeração
Toda validação acontece antes de reservar o RPS. Rejeição da prefeitura consome número e deixa buraco na numeração, e buraco na numeração o fisco cobra explicação.
Webhook com assinatura
O mesmo X-Webhook-Token que você já valida, mais um HMAC-SHA256 do corpo
para quem quiser conferir integridade. Falha vira reentrega: 16 tentativas com recuo de 1 a 360
minutos, ao longo de quase três dias.
DANFSe e XML guardados
PDF gerado do XML autorizado e o XML como a prefeitura devolveu, guardados por cinco anos. Os dois exigem o seu token: aqui não existe link público de documento fiscal.
Certificado em cofre, com termo
O A1 fica cifrado, acessível apenas ao processo que assina, sob termo de custódia assinado. Um vigia avisa o contato do emissor a partir de 30 dias do vencimento.
Medição aberta do uso
GET /v2/uso devolve quantidade e valor por status no mês. A fatura conta a nota
que recebeu número da prefeitura, em produção: recusada na validação não recebe número e
não entra na conta.
O que o TexFiscal não faz
Esta seção existe porque a decisão de integrar é sua, e decisão boa precisa do lado que não aparece em página de vendas. Se algum item aqui for impeditivo para o seu caso, é melhor você descobrir agora do que na véspera de subir.
- Só NFS-e: não emitimos NF-e de mercadoria nem NFC-e de varejo. Se o seu produto precisa dos três documentos numa integração só, não somos a escolha certa.
- 85 cidades, não o país inteiro: a cobertura é a que está publicada acima, e cresce por driver escrito e homologado, não por promessa.
- IBS e CBS: o grupo sai, mas os códigos são seus. Desde 02/09/2026 o
servico.ibs_cbsé aceito, validado e emitido no XML, e o schema do provedor é conferido em bancada. O que não fazemos é escolher CST, classificação tributária e indicador de operação por você: isso é enquadramento tributário, sai do seu contador, e não existe default. Os três podem ficar no cadastro do seu emissor para você não repetir em cada nota. O destaque passa a ser exigido em 01/10/2026 para quem está fora do Simples e em 01/01/2027 para o Simples Nacional e o MEI. - Tomador no exterior não é atendido hoje: o país do tomador é fixo em Brasil.
- Não temos painel web de notas: a operação é por API. Consulta, PDF, XML e uso são endpoints, não telas.
E três coisas que nunca fazemos, por decisão de projeto: reenviar sozinho uma nota sem
resposta conclusiva, porque reenvio duplica documento fiscal; truncar ou arrumar dado fiscal
em silêncio, porque cortar um nome ou arredondar um valor produz uma nota diferente da que
você pediu e você só descobre na apuração; e responder 502, 503 ou 504 em rota de API,
porque a borda troca o corpo dessas respostas e o seu fetch cairia no catch sem
a mensagem que explicaria o problema.
Sem taxa de setup, sem cobrança por nota recusada
Você escolhe a franquia que cabe no seu volume e paga isso, todo mês. Nota recusada na validação não conta: recusa é trabalho que evitamos para você, não serviço prestado. Homologação é ilimitada e não entra na conta.
Solo
- Até 50 notas autorizadas
- 1 CNPJ emissor
- Homologação ilimitada
- Webhook e DANFSe
Start
- Até 300 notas autorizadas
- Até 3 CNPJs emissores
- Homologação ilimitada
- Suporte na migração
Growth
- Até 1.000 notas autorizadas
- CNPJs emissores sem limite
- Homologação ilimitada
- Acompanhamento na virada
O que costumam perguntar antes de integrar
Migrar do meu emissor atual exige mexer no código?
Se o seu cliente HTTP já usa o contrato REST v2 nos caminhos de NFS-e, a troca é da URL base e do token. O que pode exigir ajuste é o que você faz com o link do PDF: em vários emissores o DANFSe vem por link público; aqui o PDF exige o seu token, então quem hoje entrega o link direto ao usuário final precisa passar a baixar pelo servidor e servir pelo próprio domínio. É uma função, não uma reescrita, e mostramos como fazer.
Como vocês chegaram no número de cidades?
Uma ferramenta baixa o WSDL do webservice de cada prefeitura candidata, remove o que é específico do host e compara a impressão digital com a do município onde o emissor está homologado. Entra na lista só quem devolve o mesmo contrato, porque duas prefeituras que dizem "usar ABRASF" podem ter envelopes diferentes, e envelope diferente é driver diferente. O método fica publicado no próprio endpoint, junto com a data.
Quem guarda o certificado digital?
O A1 fica cifrado num cofre acessível apenas ao processo que assina, sob termo de custódia assinado por você. Não trafega, não é copiado para backup em claro e não aparece em log. Um vigia acompanha a validade e avisa com antecedência, a nós e ao titular, porque certificado vencido para a emissão inteira em silêncio.
E se a nota ficar em processamento e eu não souber o desfecho?
Consulte. A consulta pergunta à prefeitura antes de responder, e é por isso que ela resolve e o reenvio não. Reenviar uma nota sem resposta conclusiva duplica documento fiscal, e documento fiscal duplicado se resolve com o contador, não com código. Se preferir não ficar consultando, cadastre um webhook.
Vocês estão prontos para a Reforma Tributária?
O grupo de IBS e CBS já é aceito, validado e emitido no XML, e o XML gerado é conferido contra o schema do provedor a cada mudança. O destaque passa a ser exigido em 01/10/2026 para quem está fora do Simples e em 01/01/2027 para o Simples Nacional e o MEI, então dá para integrar agora e ligar depois.
Uma coisa nós deliberadamente não fazemos: escolher os códigos. CST, classificação tributária e indicador de operação são enquadramento tributário, e um default nosso sairia autorizado pela prefeitura e errado na sua apuração, que é o pior tipo de erro. Você informa no payload ou deixa no cadastro do emissor, e o payload sempre vence o cadastro, porque um mesmo CNPJ pode emitir em atividades com classificação diferente.
O grupo é tudo ou nada: com metade dos códigos a nota é recusada aqui, antes de consumir numeração de RPS, e não na prefeitura depois de consumir.
Posso testar antes de assinar qualquer coisa?
Sim, e é o caminho recomendado. A homologação é completa e fala com o ambiente de teste da prefeitura: mesma API, mesmo token no formato final, sem valor fiscal e sem custo. Nota emitida em homologação não vale para o seu cliente nem para a prefeitura, e existe para ensaiar.
Comece pela homologação, não pela assinatura
Peça o acesso de teste, integre com calma e só decida depois de ver o seu próprio payload virando nota. Se você já emite por API hoje, mande o payload atual: a gente responde dizendo exatamente o que muda, que costuma ser nada.