NFS-e

Visão geral e fluxo de integração

A autenticação é idêntica à da NF-e: cabeçalhos token / timestamp / sign, veja Autenticação.

Três diferenças estruturais em relação à NF-e

1. A chave de acesso tem 50 dígitos e é gerada pelo emissor oficial. A chave de 44 dígitos da NF-e é calculada pelo contribuinte; a chave da NFS-e só existe depois que a autoridade aceita o documento. Um documento que falhou, portanto, não tem chaveAcesso e só pode ser localizado por identificacaoDps, o identificador de DPS de 45 caracteres que geramos.

2. A nota de serviço é regida pelo município. A plataforma roteia pelo município do emitente; o canal resultante aparece como padraoMunicipal na resposta da consulta. Hoje há suporte ao padrão nacional (Nacional) e ao sistema municipal de São Paulo (Paulistana); um município não suportado é rejeitado na aceitação (10018010) em vez de aceito e falhado de forma assíncrona.

3. O cancelamento tem janela, e fora dela a resposta não é "não dá para cancelar" e sim "vai para análise municipal". Veja Cancelar NFS-e.

Pré-requisitos

• O emitente precisa estar aprovado e com certificado utilizável, caso contrário a aceitação é rejeitada (10018004).
• O emitente precisa ter perfil de NFS-e, criado pela seção emissaoNFSe de Registrar empresa ou mantido pela operação no console. Enquadramento no Simples, apuração no Simples, regime especial e série do DPS vêm sempre do perfil; a requisição de emissão não os envia nem os substitui. Sem perfil, a aceitação recusa (10018005). Código de serviço, CNAE, NBS e os demais campos do serviço não ficam no perfil: vão em cada nota.
• O ambienteEmissao precisa coincidir com o ambiente atual do emitente. Após o registro o emitente fica no ambiente de testes (Homologacao); a virada para produção é ação da operação e não é exposta pela API.
• Os valores de tributação seguem a requisição: o que ela traz prevalece, e só o que falta a plataforma busca nos dados de referência fiscal, como a lista da LC 116, a classificação e as alíquotas de retenção federal e a carga aproximada do IBPT. Se os dados que a retenção federal, as alíquotas próprias de PIS/COFINS ou o local de incidência do ISS precisam consultar ainda não foram importados, a aceitação recusa com 10018065, listando os campos da requisição que podem substituí-los.
• Quando o tomador é pessoa jurídica (CNPJ) há retenção federal: envie os valores em servico.retencoes, em que zero declara que não há retenção, ou omita-os junto com pisCofins.tipoRetencao e a plataforma os determina pela classificação oficial de retenção do serviço e por cliente.orgaoPublico e cliente.optanteSimplesNacional; enviar pisCofins.tipoRetencao sem os valores é recusado (10018001). Informação faltante é rejeitada explicitamente (10018023) com tudo o que falta listado de uma vez, em vez de tratada como zero.

Restrições adicionais do canal Paulistana

Um emitente de São Paulo (padraoMunicipal = Paulistana) precisa do CCM (inscricaoMunicipal): se estiver no perfil, é usado como está; se faltar, a plataforma consulta o sistema municipal por CNPJ na aceitação e grava o resultado no perfil; a aceitação só é rejeitada (10018005) quando nada é encontrado.

O canal não suporta campos de desconto: incorpore o desconto ao valor do serviço ou à dedução. Também não suporta emissão substitutiva (o layout municipal de RPS não tem esse grupo): cancele a original e emita uma nova; enviar o grupo é rejeitado na aceitação (10018001).

Ele também ganha duas capacidades automáticas que não exigem nenhum endpoint novo: as notas paulistanas recebidas são puxadas direto do sistema municipal para a lista de recebidas (origem=PrefeituraSP, mescladas automaticamente quando a transcrição da ADN chega); uma nota emitida e cancelada no portal municipal é sincronizada para Cancelada e o nfse.canceled é enviado normalmente.

Máquina de estados

                 ┌──────────────► Negada (terminal)
                 │
Pendente ────────┼──────────────► Autorizada ──┬──► Cancelada (terminal)
                 │                             │
                 └──────────────► Falha        ├──► EmProcessoDeCancelamento ──┬──► Cancelada
                   (falhou antes da numeração, │                               └──► Autorizada (análise indeferida)
                    nenhum documento existe)   └──► Substituida (substituída)

Status de manifestação de uma nota recebida

O status de uma nota recebida usa Autorizada / Cancelada / Substituida da tabela acima; a manifestação deste emitente fica separada no bloco manifestacao, e cada parte manifesta no máximo uma vez por nota.

(sem manifestação, filtro da lista Pendente) ──┬──► Confirmada (confirmada por este emitente, terminal)
                                               ├──► Rejeitada (rejeitada por este emitente) ──► RejeicaoAnulada (rejeição anulada pelo município, terminal)
                                               └──► ConfirmacaoTacita (confirmação tácita do município, terminal)

Callbacks de webhook

Entregues na URL que você registra como carga JSON pura.

Nota: Semântica das assinaturas. Um aplicativo que nunca registrou nenhuma linha de assinatura recebe todos os seis eventos de saída. Assim que existir qualquer linha de assinatura para o aplicativo (por exemplo um evento de entrada), ele passa ao modo lista de permissão e só os eventos explicitamente habilitados são entregues. Ao assinar eventos de entrada, habilite também os eventos de saída necessários, senão as notificações de saída ficam paradas aguardando destinatário.

{
  "tipo": "NFS-e",
  "empresaId": "1001",
  "nfseId": "PED-20260918-001",
  "nfseStatus": "Autorizada",
  "nfseMotivoStatus": null,
  "nfseLinkDanfse": "https://api.v2.tffiscal.com/openapi/files/danfse/…",
  "nfseLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9001?token=…",
  "nfseNumero": "1287",
  "nfseSerie": "1",
  "nfseChaveAcesso": "3550308…",
  "nfseIdentificacaoDps": "DPS3550308…",
  "nfseDataEmissao": "2026-09-18T13:00:00Z",
  "nfseDataAutorizacao": "2026-09-18T13:00:03Z",
  "nfseNumeroProtocolo": null,
  "nfseAtualizadoEm": "2026-09-18T13:00:03Z"
}

nfseAtualizadoEm é o momento desta mudança de estado. A ordem de entrega não é garantida: retentativas e múltiplas instâncias podem fazer um evento antigo chegar depois de um novo. Compare com o horário que você já tem e descarte o mais antigo em vez de sobrescrever o estado pela ordem de chegada.

Num callback de falha o nfseChaveAcesso pode vir vazio (a autoridade nunca gerou a chave); concilie por nfseIdentificacaoDps nesse caso. Um callback de falha anterior à numeração não traz nenhum dos dois, e só o nfseId concilia.

Modelo de erros

Os endpoints públicos retornam um array puro:

[{"codigo": "10018012", "mensagem": "Codigo de servico fora da lista oficial LC 116: 999999"}]

Erros de autenticação e autorização (10009xxx) estão em Autenticação; a tabela completa está em Códigos de erro.

Checklist de integração

1. Registre o emitente (com emissaoNFSe) → vincule o certificado → registre o webhook.
2. Emita uma nota mínima em Homologacao (só os campos obrigatórios), confirme que o nfse.authorized chega e que o XML e o DANFSe baixam.
3. Envie o mesmo id outra vez e confirme que nenhuma segunda nota é emitida.
4. Envie um código de serviço inexistente e confirme a recusa síncrona 10018012, e não uma Negada assíncrona.
5. Cancele uma nota autorizada e confirme que ela chega a Cancelada ou EmProcessoDeCancelamento conforme a janela.
6. Consulte um documento que falhou e confirme que ele concilia por identificacaoDps, não por chaveAcesso.
7. Manifeste sobre uma nota recebida com tipo=Confirmacao e veja o detalhe trazer manifestacao.status=Confirmada; envie tipo=Rejeicao na mesma nota e confirme o 10018042 (cada parte manifesta uma vez).