NFS-e

Capabilities and onboarding flow

Authentication is identical to NF-e: headers token / timestamp / sign, see Authentication.

Three structural differences from NF-e

1. The access key is 50 digits and is generated by the issuing authority. An NF-e's 44-digit key is computed by the taxpayer; an NFS-e key only exists once the authority has accepted the document. A failed document therefore has no chaveAcesso and can only be located by identificacaoDps, the 45-character DPS identifier we generate.

2. Service invoices are governed by the municipality. The platform routes by the issuer's municipality; the resulting channel appears as padraoMunicipal in the query response. The national standard (Nacional) and the São Paulo municipal system (Paulistana) are supported today; an unsupported municipality is rejected at acceptance (10018010) rather than accepted and failed asynchronously.

3. Cancellation has a window, and outside it the answer is not "you cannot cancel" but "it goes to municipal review". See Cancel NFS-e.

Prerequisites

• The issuer must be approved with a usable certificate, otherwise acceptance is rejected (10018004).
• The issuer must have an NFS-e profile, created through the emissaoNFSe section of Register company or maintained by operations in the console. Simples status, Simples assessment, special regime and DPS series always come from the profile; the issuance request neither sends nor overrides them. Without a profile, acceptance rejects (10018005). Service code, CNAE, NBS and the other service-level fields are not in the profile: they go with every invoice.
• ambienteEmissao must match the issuer's current environment. After registration an issuer sits in the test environment (Homologacao); switching to production is an operations action and is not exposed through the API.
• Tax values follow the request: what it carries prevails, and only what is missing is looked up by the platform in the tax reference data, such as the LC 116 list, the federal withholding classification and rates and the IBPT approximate burden. When the data needed for federal withholding, the own PIS/COFINS rates or the ISS place of taxation has not been imported yet, acceptance rejects with 10018065, listing the request fields that can replace it.
• When the recipient is a legal entity (CNPJ), federal withholding applies: send the amounts in servico.retencoes, where zero declares no withholding, or omit them together with pisCofins.tipoRetencao and the platform determines them from the official withholding classification of the service plus cliente.orgaoPublico and cliente.optanteSimplesNacional; sending pisCofins.tipoRetencao without the amounts is rejected (10018001). Missing information is rejected explicitly (10018023) with every missing item listed at once, rather than treated as zero.

Extra constraints on the São Paulo channel

A São Paulo issuer (padraoMunicipal = Paulistana) needs its municipal registration CCM (inscricaoMunicipal): when it is in the issuer profile it is used as is; when it is missing the platform queries the municipal system by CNPJ at acceptance and stores the result in the profile; acceptance is rejected (10018005) only when nothing is found.

The channel does not support discount fields: fold discounts into the service amount or the deduction. It does not support substitute issuance either (the municipal RPS layout has no such group): cancel the original and issue a new one; sending it is rejected at acceptance (10018001).

It also gets two automatic capabilities that need no new endpoint: São Paulo invoices it receives are pulled directly from the municipal system into the inbound list (origem=PrefeituraSP, merged automatically once the ADN transcription arrives); an outbound invoice cancelled on the municipal portal is synchronized to Cancelada and nfse.canceled is sent as usual.

State machine

                 ┌──────────────► Negada (terminal)
                 │
Pendente ────────┼──────────────► Autorizada ──┬──► Cancelada (terminal)
                 │                             │
                 └──────────────► Falha        ├──► EmProcessoDeCancelamento ──┬──► Cancelada
                   (failed before numbering,   │                               └──► Autorizada (review refused)
                    no document exists)        └──► Substituida (replaced)

Manifestation status of a received invoice

A received invoice's status uses Autorizada / Cancelada / Substituida from the table above; this issuer's manifestation is kept separately in the manifestacao block, and each party manifests at most once per invoice.

(not manifested, list filter Pendente) ──┬──► Confirmada (confirmed by this issuer, terminal)
                                         ├──► Rejeitada (rejected by this issuer) ──► RejeicaoAnulada (rejection annulled by the municipality, terminal)
                                         └──► ConfirmacaoTacita (tacit confirmation by the municipality, terminal)

Webhook callbacks

Delivered to the URL you register as a bare JSON payload.

Note: Subscription semantics. An app that has never registered any subscription row receives all six outbound events. As soon as any subscription row exists for the app (for example an inbound event), the app switches to allow-list mode and only explicitly enabled events are delivered. When subscribing to inbound events, enable the outbound events you need as well, otherwise outbound notifications stay parked waiting for a target.

{
  "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 is the moment of this state change. Delivery order is not guaranteed: retries and multiple instances can make an older event arrive after a newer one. Compare it with the timestamp you already hold and drop the older one instead of overwriting state in arrival order.

On a failure callback nfseChaveAcesso may be empty (the authority never generated a key); reconcile by nfseIdentificacaoDps then. A callback for a failure before numbering carries neither, so only nfseId can reconcile it.

Error model

Public endpoints return a bare array:

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

Authentication and authorization errors (10009xxx) are in Authentication; the full table is in Error codes.

Integration checklist

1. Register the issuer (with emissaoNFSe) → bind the certificate → register the webhook.
2. Issue a minimal invoice in Homologacao (required fields only), confirm nfse.authorized arrives and that the XML and DANFSe download.
3. Submit the same id again and confirm no second invoice is issued.
4. Send a service code that does not exist and confirm a synchronous 10018012 refusal rather than an asynchronous Negada.
5. Cancel an authorized invoice and confirm it reaches Cancelada or EmProcessoDeCancelamento depending on the window.
6. Query a failed document and confirm it reconciles by identificacaoDps rather than chaveAcesso.
7. Manifest on a received invoice with tipo=Confirmacao, then check the detail shows manifestacao.status=Confirmada; send tipo=Rejeicao on the same invoice and confirm 10018042 (each party manifests once).