REFERÊNCIA DA API

NFS-e

Notas de serviços, XML e cancelamentos.

GET/homologation/nfse#

Listar documentos locais

Permissão necessária nfse:read

Parâmetros

pagequery · integer

per_pagequery · integer

searchquery · string

Respostas HTTP

200

Sucesso

Ver campos da resposta

dataarrayobrigatório

data[].idintegerobrigatório

data[].modelstringobrigatório

data[].environmentintegerobrigatório

data[].sourcestring

data[].seriesnullable

data[].numbernullable

data[].nfse_numbernullable

data[].statusstringobrigatório

data[].access_keynullable

data[].dps_idnullable

data[].recipient_namenullable

data[].recipient_documentnullable

data[].totalnullable

data[].issued_atnullable

metaobjectobrigatório

meta.pageintegerobrigatório

meta.per_pageintegerobrigatório

meta.totalintegerobrigatório

meta.last_pageintegerobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

POST/homologation/nfse#

Preparar rascunho com XSD e certificado; não transmitir

Permissão necessária nfse:draft

Parâmetros

Idempotency-Keyheader · stringobrigatório

UUID obrigatório em POST/PATCH. Mesmo owner/ambiente/chave com operação ou conteúdo diferente retorna 409.

Corpo da requisição application/json · 14 campos

customer_idintegerobrigatório

service_idintegerobrigatório

seriesstringobrigatório

Inteiro entre 1 e 49999.

numberstringobrigatório

competencestringobrigatório

Até hoje e anterior a 2027-01-01 no recorte atual.

performance_municipalitystringobrigatório

amountstringobrigatório

simple_ratestringobrigatório

withholdinginteger

Valores: 1, 2

iss_ratenullable

municipal_codenullable

descriptionstringobrigatório

scope_confirmedbooleanobrigatório

retention_review_confirmedboolean

Confirmação explícita da revisão de retenção desta operação; exigida pelo preflight quando aplicável. Não substitui parâmetros municipais nem aceita retenção arbitrária.

Respostas HTTP

201

Sucesso

Ver campos da resposta

dataobjectobrigatório

data.idintegerobrigatório

data.modelstringobrigatório

data.environmentintegerobrigatório

data.sourcestring

data.seriesnullable

data.numbernullable

data.nfse_numbernullable

data.statusstringobrigatório

data.access_keynullable

data.dps_idnullable

data.recipient_namenullable

data.recipient_documentnullable

data.totalnullable

data.issued_atnullable

data.reviewed_hashstring

data.reviewobject

Snapshot revisado de emitente, destinatário, serviço/itens e parâmetros, sem XML ou credenciais.

data.transmissionsarray

data.transmissions[].idintegerobrigatório

data.transmissions[].document_idintegerobrigatório

data.transmissions[].statestringobrigatório

data.transmissions[].resultnullableobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse' \
  -X POST \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: AQUI_VAI_O_UUID' \
  --data '{
  "customer_id": 1,
  "service_id": 1,
  "series": "AQUI_VAI_O_VALOR",
  "number": "AQUI_VAI_O_VALOR",
  "competence": "2026-11-06",
  "performance_municipality": "AQUI_VAI_O_VALOR",
  "amount": "AQUI_VAI_O_VALOR",
  "simple_rate": "AQUI_VAI_O_VALOR",
  "description": "AQUI_VAI_O_VALOR",
  "scope_confirmed": true
}'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

Exemplo de estrutura: substitua IDs, valores e UUIDs pelos dados conferidos da sua operação. O portal não executa este código.

GET/homologation/nfse/{id}#

Documento e revisão local

Permissão necessária nfse:read

Parâmetros

idpath · integerobrigatório

Respostas HTTP

200

Sucesso

Ver campos da resposta

dataobjectobrigatório

data.idintegerobrigatório

data.modelstringobrigatório

data.environmentintegerobrigatório

data.sourcestring

data.seriesnullable

data.numbernullable

data.nfse_numbernullable

data.statusstringobrigatório

data.access_keynullable

data.dps_idnullable

data.recipient_namenullable

data.recipient_documentnullable

data.totalnullable

data.issued_atnullable

data.reviewed_hashstring

data.reviewobject

Snapshot revisado de emitente, destinatário, serviço/itens e parâmetros, sem XML ou credenciais.

data.transmissionsarray

data.transmissions[].idintegerobrigatório

data.transmissions[].document_idintegerobrigatório

data.transmissions[].statestringobrigatório

data.transmissions[].resultnullableobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

POST/homologation/nfse/{id}/transmissions#

Solicitar transmissão em fila

Permissão necessária nfse:transmit

Parâmetros

idpath · integerobrigatório

Idempotency-Keyheader · stringobrigatório

UUID obrigatório em POST/PATCH. Mesmo owner/ambiente/chave com operação ou conteúdo diferente retorna 409.

Corpo da requisição application/json · 2 campos

confirmedbooleanobrigatório

reviewed_hashstringobrigatório

Respostas HTTP

202

Aceito para processamento; não significa autorização fiscal.

Ver campos da resposta

dataobjectobrigatório

data.request_idintegerobrigatório

data.document_idintegerobrigatório

data.event_idinteger

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/transmissions' \
  -X POST \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: AQUI_VAI_O_UUID' \
  --data '{
  "confirmed": true,
  "reviewed_hash": "AQUI_VAI_O_VALOR"
}'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

Exemplo de estrutura: substitua IDs, valores e UUIDs pelos dados conferidos da sua operação. O portal não executa este código.

GET/homologation/nfse/{id}/transmissions#

Listar tentativas locais

Permissão necessária nfse:read

Parâmetros

idpath · integerobrigatório

Respostas HTTP

200

Sucesso

Ver campos da resposta

dataarrayobrigatório

data[].idintegerobrigatório

data[].document_idintegerobrigatório

data[].statestringobrigatório

data[].resultnullableobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/transmissions' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

GET/homologation/nfse/{id}/transmissions/{attempt}#

Consultar tentativa local

Permissão necessária nfse:read

Parâmetros

idpath · integerobrigatório

attemptpath · integerobrigatório

Respostas HTTP

200

Sucesso

Ver campos da resposta

dataobjectobrigatório

data.idintegerobrigatório

data.document_idintegerobrigatório

data.statestringobrigatório

data.resultnullableobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/transmissions/{attempt}' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

POST/homologation/nfse/{id}/transmissions/{attempt}/reconcile#

Consultar autorizador em fila, sem reenviar

Permissão necessária nfse:transmit

Parâmetros

idpath · integerobrigatório

attemptpath · integerobrigatório

Idempotency-Keyheader · stringobrigatório

UUID obrigatório em POST/PATCH. Mesmo owner/ambiente/chave com operação ou conteúdo diferente retorna 409.

Respostas HTTP

202

Aceito para processamento; não significa autorização fiscal.

Ver campos da resposta

dataobjectobrigatório

data.request_idintegerobrigatório

data.document_idintegerobrigatório

data.event_idinteger

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/transmissions/{attempt}/reconcile' \
  -X POST \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: AQUI_VAI_O_UUID' \
  --data '{}'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

Exemplo de estrutura: substitua IDs, valores e UUIDs pelos dados conferidos da sua operação. O portal não executa este código.

GET/homologation/nfse/{id}/xml#

Baixar arquivo local verificado

Permissão necessária nfse:read

Parâmetros

idpath · integerobrigatório

Respostas HTTP

200

Sucesso

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/xml' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

GET/homologation/nfse/{id}/cancellations#

Listar eventos locais do documento

Permissão necessária nfse:cancel

Parâmetros

idpath · integerobrigatório

pagequery · integer

per_pagequery · integer

Respostas HTTP

200

Sucesso

Ver campos da resposta

dataarrayobrigatório

data[].idintegerobrigatório

data[].document_idintegerobrigatório

data[].environmentintegerobrigatório

data[].typestringobrigatório

data[].sequenceintegerobrigatório

data[].statestringobrigatório

data[].reasonstringobrigatório

data[].reason_codeinteger | null

data[].reviewed_hashstringobrigatório

data[].created_atstringobrigatório

data[].resultnullableobrigatório

metaobjectobrigatório

meta.pageintegerobrigatório

meta.per_pageintegerobrigatório

meta.totalintegerobrigatório

meta.last_pageintegerobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/cancellations' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

POST/homologation/nfse/{id}/cancellations#

Preparar evento assinado para revisão, sem transmissão

Permissão necessária nfse:cancel

Parâmetros

idpath · integerobrigatório

Idempotency-Keyheader · stringobrigatório

UUID obrigatório em POST/PATCH. Mesmo owner/ambiente/chave com operação ou conteúdo diferente retorna 409.

Corpo da requisição application/json · 3 campos

reasonstringobrigatório

conditions_acceptedbooleanobrigatório

reason_codeintegerobrigatório

Valores: 1, 2, 9

Respostas HTTP

201

Sucesso

Ver campos da resposta

dataobjectobrigatório

data.idintegerobrigatório

data.document_idintegerobrigatório

data.environmentintegerobrigatório

data.typestringobrigatório

data.sequenceintegerobrigatório

data.statestringobrigatório

data.reasonstringobrigatório

data.reason_codeinteger | null

data.reviewed_hashstringobrigatório

data.created_atstringobrigatório

data.resultnullableobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/cancellations' \
  -X POST \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: AQUI_VAI_O_UUID' \
  --data '{
  "reason": "AQUI_VAI_O_VALOR",
  "conditions_accepted": true,
  "reason_code": 1
}'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

Exemplo de estrutura: substitua IDs, valores e UUIDs pelos dados conferidos da sua operação. O portal não executa este código.

GET/homologation/nfse/{id}/cancellations/{event}#

Consultar evento local e hash de revisão

Permissão necessária nfse:cancel

Parâmetros

idpath · integerobrigatório

eventpath · integerobrigatório

Respostas HTTP

200

Sucesso

Ver campos da resposta

dataobjectobrigatório

data.idintegerobrigatório

data.document_idintegerobrigatório

data.environmentintegerobrigatório

data.typestringobrigatório

data.sequenceintegerobrigatório

data.statestringobrigatório

data.reasonstringobrigatório

data.reason_codeinteger | null

data.reviewed_hashstringobrigatório

data.created_atstringobrigatório

data.resultnullableobrigatório

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/cancellations/{event}' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

POST/homologation/nfse/{id}/cancellations/{event}/transmissions#

Enfileirar envio do evento confirmado

Revalida credencial antes do envio. Evento já submetido é apenas observado, nunca reenviado. NF-e exige revisão com menos de 15 minutos; descarte e prepare novamente apenas eventos ainda não enviados.

Permissão necessária nfse:cancel

Parâmetros

idpath · integerobrigatório

eventpath · integerobrigatório

Idempotency-Keyheader · stringobrigatório

UUID obrigatório em POST/PATCH. Mesmo owner/ambiente/chave com operação ou conteúdo diferente retorna 409.

Corpo da requisição application/json · 2 campos

confirmedbooleanobrigatório

reviewed_hashstringobrigatório

Respostas HTTP

202

Aceito para processamento, sem garantia de autorização fiscal.

Ver campos da resposta

dataobjectobrigatório

data.request_idintegerobrigatório

data.document_idintegerobrigatório

data.event_idinteger

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/cancellations/{event}/transmissions' \
  -X POST \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: AQUI_VAI_O_UUID' \
  --data '{
  "confirmed": true,
  "reviewed_hash": "AQUI_VAI_O_VALOR"
}'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

Exemplo de estrutura: substitua IDs, valores e UUIDs pelos dados conferidos da sua operação. O portal não executa este código.

POST/homologation/nfse/{id}/cancellations/{event}/reconcile#

Enfileirar consulta do evento, sem retransmissão

Permissão necessária nfse:cancel

Parâmetros

idpath · integerobrigatório

eventpath · integerobrigatório

Idempotency-Keyheader · stringobrigatório

UUID obrigatório em POST/PATCH. Mesmo owner/ambiente/chave com operação ou conteúdo diferente retorna 409.

Respostas HTTP

202

Aceito para processamento, sem garantia de autorização fiscal.

Ver campos da resposta

dataobjectobrigatório

data.request_idintegerobrigatório

data.document_idintegerobrigatório

data.event_idinteger

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/cancellations/{event}/reconcile' \
  -X POST \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: AQUI_VAI_O_UUID' \
  --data '{}'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.

Exemplo de estrutura: substitua IDs, valores e UUIDs pelos dados conferidos da sua operação. O portal não executa este código.

GET/homologation/nfse/{id}/cancellations/{event}/xml#

Baixar XML do evento autorizado e validado

Permissão necessária nfse:cancel

Parâmetros

idpath · integerobrigatório

eventpath · integerobrigatório

Respostas HTTP

200

Sucesso

default

Erro seguro; 401/403/404/409/415/422/429/500/503. 429 inclui Retry-After.

Ver campos da resposta

errorobjectobrigatório

error.codestringobrigatório

error.messagestringobrigatório

errorsobject

curl 'https://api.nf3.app/api/v1/homologation/nfse/{id}/cancellations/{event}/xml' \
  -H 'Authorization: Bearer AQUI_VAI_A_CHAVE' \
  -H 'Accept: application/json'

Substitua os placeholders no seu servidor. Nenhuma requisição é executada aqui.