Endpoints — NFS-e Inbound
Resumo curado dos endpoints. O contrato completo (schemas, exemplos, "Try it") está na referência gerada da API.
Base URL:
https://api.nfse.io· Auth: API Key (papelNota FiscalouNFSeDist;Managementpara manutenção) — veja Autenticação.
Empresas (configuração de captura)
| Método | Path | Propósito |
|---|---|---|
GET | /v2/companies/inbound/nfse | Lista empresas com captura |
POST | /v2/companies/inbound/nfse | Cadastra empresa (201; 409 se duplicada) |
GET | /v2/companies/{companyId}/inbound/nfse/details | Detalhe da configuração |
PUT | /v2/companies/{companyId}/inbound/nfse/details | Atualiza (webhookUrl, manifestação automática, isActive) |
DELETE | /v2/companies/{companyId}/inbound/nfse/details | Desativa a captura |
POST | /v2/companies/{companyId}/inbound/nfse/reset-nsu | Redefine o cursor NSU |
Documentos (consulta e conteúdo)
| Método | Path | Propósito |
|---|---|---|
GET | .../inbound/nfse | Lista documentos (filtros por período, tipo, status, NSU…) |
GET | .../inbound/nfse/{id} | Detalhe do documento |
GET | .../inbound/nfse/{id}/xml | XML (302 para URL assinada) |
GET | .../inbound/nfse/{id}/pdf | DANFSe (302; 202 se em geração) |
GET | .../inbound/nfse/{id}/json | XML convertido em JSON |
POST | .../inbound/nfse/{id}/reprocess | Reenfileira o documento |
POST | .../inbound/nfse/{id}/resend-webhook | Reenvia o webhook |
Manifestação (tomador)
| Método | Path | Propósito |
|---|---|---|
POST | .../inbound/nfse/by-access-key/{accessKey}/manifestations?eventCode={203202|203206} | Envia manifestação (202 Pending) |
GET | .../inbound/nfse/by-access-key/{accessKey}/manifestations | Lista manifestações |
GET | .../inbound/nfse/manifestations/{id} | Detalhe + XMLs request/response |
Manutenção (papel Management)
| Método | Path |
|---|---|
POST | .../inbound/nfse/maintenance/fetch-now |
GET | .../inbound/nfse/maintenance/notifications |
GET | .../inbound/nfse/maintenance/statistics |
POST | .../inbound/nfse/maintenance/reactivate |
Exemplo de detalhe de documento
Resposta real (anonimizada) de GET .../inbound/nfse/{id}:
{
"id": "<objectId>",
"companyId": "<companyId>",
"nsu": 1850,
"type": "serviceInvoice",
"accessKey": "<chave-50-digitos>",
"substituteAccessKey": null,
"generatedOn": "2026-03-20T21:15:48Z",
"issuedOn": "2026-03-20T21:15:48Z",
"accrualOn": "2026-03",
"provider": { "federalTaxNumber": "<cnpj>", "name": "<prestador>", "cityCode": "3106200", "state": "MG" },
"borrower": { "federalTaxNumber": "<cnpj>", "name": "<tomador>", "cityCode": "3550308" },
"servicesAmount": 0.10,
"serviceCode": "100501.004",
"issueCityCode": "3106200",
"description": "<descrição do serviço>",
"environment": "Development",
"status": "PdfFailed",
"failureReason": "pdf:failed:401",
"webhookStatus": "Pending",
"webhookAttempts": 0,
"reprocessCount": 0,
"hasPdf": false,
"xmlSizeBytes": 9718,
"createdAt": "2026-04-08T23:57:10.821Z"
}
Os grupos de tributos (
taxes/amounts, incl. IBS/CBS) não vêm no detalhe REST — apenas no payload do webhook.
substituteAccessKeyvem preenchido apenas quando a NFS-e substitui outra nota (substituição/cancelamento com substituta);nullcaso contrário.Código de serviço: o detalhe REST expõe
serviceCode(código municipal "achatado"). O payload do webhook detalha esse código em dois campos —federalServiceCode(item da lista nacional LC 116) ecityServiceCode(código do município) — ver Eventos de Webhook.