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

A ref vai na QUERY, não no corpo, e é a chave de idempotência.

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

Listagem paginada (50 por página) das notas do emissor no ambiente do token, da mais recente para a mais antiga, para conciliar sem consultar ref por ref. Nunca leva payload, XML nem PDF, e não pergunta à prefeitura: nota pendente aparece como está no serviço.

Roda a mesma validação da emissão (cadastro do emissor e regras do payload) e PARA antes de reservar RPS, assinar ou falar com a prefeitura. 200 quando passa; 422 requisicao_invalida com os mesmos erros[] da emissão quando não passa. Não exige certificado, então serve para homologar a integração antes de o A1 chegar. A prefeitura ainda pode recusar por regra própria dela.

Se a nota estiver em processamento, a consulta PERGUNTA à prefeitura antes de responder: é 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, então NÃO entregue este endereço ao seu usuário final: ele receberia 401 em JSON. Para mostrar o PDF a quem recebeu a nota, peça um endereço assinado em /v2/nfse/{ref}/pdf/link, que abre sem token e expira.

Devolve um endereço de curta validade que abre o PDF SEM token, para você entregar ao navegador de quem recebeu a nota (botão de e-mail, tela do cliente, WhatsApp). É a alternativa oficial ao proxy autenticado que cada integrador vinha escrevendo. O endereço vale para UM documento, expira, e não dá acesso a mais nada da conta: quem o tiver antes da expiração abre esse PDF, então entregue apenas ao destinatário da nota. A validade padrão é de 900 segundos e o teto é de 604800 (sete dias). Depois de expirar, o endereço responde uma página dizendo que o link venceu, e não JSON, porque quem lê é uma pessoa. O PDF em si não pode ser exibido dentro de um iframe (frame-ancestors none neste host): abra em aba nova ou ofereça como download.

Devolve um endereço de curta validade que abre o PDF SEM token, para você entregar ao navegador de quem recebeu a nota (botão de e-mail, tela do cliente, WhatsApp). É a alternativa oficial ao proxy autenticado que cada integrador vinha escrevendo. O endereço vale para UM documento, expira, e não dá acesso a mais nada da conta: quem o tiver antes da expiração abre esse PDF, então entregue apenas ao destinatário da nota. A validade padrão é de 900 segundos e o teto é de 604800 (sete dias). Depois de expirar, o endereço responde uma página dizendo que o link venceu, e não JSON, porque quem lê é uma pessoa. O PDF em si não pode ser exibido dentro de um iframe (frame-ancestors none neste host): abra em aba nova ou ofereça como download.

Devolve um endereço de curta validade que abre o PDF SEM token, para você entregar ao navegador de quem recebeu a nota (botão de e-mail, tela do cliente, WhatsApp). É a alternativa oficial ao proxy autenticado que cada integrador vinha escrevendo. O endereço vale para UM documento, expira, e não dá acesso a mais nada da conta: quem o tiver antes da expiração abre esse PDF, então entregue apenas ao destinatário da nota. A validade padrão é de 900 segundos e o teto é de 604800 (sete dias). Depois de expirar, o endereço responde uma página dizendo que o link venceu, e não JSON, porque quem lê é uma pessoa. O PDF em si não pode ser exibido dentro de um iframe (frame-ancestors none neste host): abra em aba nova ou ofereça como download.

Modelo 65, transmitida de forma síncrona à SEFAZ da UF do emissor. A ref vai na QUERY e é a chave de idempotência: repetir com a mesma ref devolve a nota que existe.

Toda recusa de validação (CFOP, CSOSN, GTIN, pagamento menor que o total, valor bruto diferente de quantidade x unitário) acontece ANTES de numerar. A nota recusada pela SEFAZ volta 422 com status_sefaz e mensagem_sefaz, e pode ser reenviada com a MESMA ref (mesmo número, mesma chave) depois de corrigida; número DENEGADO não volta.

Sem desfecho (SEFAZ fora do ar, timeout) a resposta é 202: NUNCA reenvie, consulte. A NFC-e exige CSC cadastrado no emissor (produção) e só aceita CFOP de venda a consumidor.

Listagem paginada (50 por página) das NFC-e do emissor no ambiente do token, da mais recente para a mais antiga, para conciliar sem consultar ref por ref. Nunca leva payload nem XML, e não pergunta à SEFAZ: nota pendente aparece como está no serviço.

Roda a mesma validação da emissão (habilitação, UF, cadastro do emissor, CFOP, CSOSN, GTIN, pagamentos, totais) e PARA antes de numerar, assinar e transmitir. 200 quando passa; 422 requisicao_invalida com os mesmos erros[] da emissão quando não passa. Não consome número da série nem toca a SEFAZ, que ainda pode recusar por regra própria dela.

Cupom de bobina de 80mm, com a altura ajustada ao número de itens e o QR Code da consulta desenhado. É a representação impressa; o documento fiscal continua sendo o XML.

Nota pendente: a consulta pergunta a SEFAZ pela chave (no máximo uma vez a cada 15 s). Nota recusada volta 422 com o motivo da SEFAZ.

Só nota autorizada cancela. O prazo é da SEFAZ (24 h para NF-e; NFC-e na Bahia, 30 minutos sem circulação da mercadoria): fora dele a resposta é 422 cancelamento_recusado com o cStat. A justificativa (15 a 255 caracteres) VAI à SEFAZ no evento 110111.

Recuperação: devolve a nota deste emissor com a série e o número informados, no ambiente do token, com a mesma representação do GET por ref. Use quando a resposta do POST se perdeu (timeout, rede) e o seu sistema não gravou a ref: antes de reenviar o mesmo número, pergunte se ele já existe. Nota de outro emissor responde 404, igual a número inexistente.

Recuperação pela chave de acesso de 44 posições (a do DANFE e do Id do XML), com ou sem o prefixo NFe e aceitando o CNPJ alfanumérico, escopada ao emissor do token e ao ambiente. Chave de outro emissor responde 404, igual a chave inexistente; chave com dígito verificador errado responde 422 chave_invalida.

NFe assinada + protNFe, exatamente como a SEFAZ autorizou. É o arquivo que o emitente guarda por 5 anos e manda ao contador. Também aceito como /{ref}/xml.

Cada pedido de inutilização do emissor neste ambiente (homologado ou recusado), mais recente primeiro. Desde 22/09/2026 o procInutNFe é guardado e entra no ZIP do mês do painel.

Declara à SEFAZ que os números de numero_inicial a numero_final da série não serão usados. Faixa com número já usado é recusada antes de ir à SEFAZ.

Modelo 55, transmitida de forma síncrona à SEFAZ da UF do emissor. A ref vai na QUERY e é a chave de idempotência: repetir com a mesma ref devolve a nota que existe.

Toda recusa de validação (CFOP, CSOSN, GTIN, pagamento menor que o total, valor bruto diferente de quantidade x unitário) acontece ANTES de numerar. A nota recusada pela SEFAZ volta 422 com status_sefaz e mensagem_sefaz, e pode ser reenviada com a MESMA ref (mesmo número, mesma chave) depois de corrigida; número DENEGADO não volta.

Sem desfecho (SEFAZ fora do ar, timeout) a resposta é 202: NUNCA reenvie, consulte. A NF-e exige destinatário identificado com endereço completo.