---
title: "Endpoints — NFS-e Inbound"
description: "Referência curada dos endpoints REST da recepção de NFS-e: empresas, documentos, downloads, manifestação e manutenção."
source_url: https://nfe.io/docs/distribuicao-nfse-inbound-endpoints/
last_updated: 2026-08-19
---

# Endpoints — NFS-e Inbound

Resumo curado dos endpoints. O contrato completo (schemas, exemplos, "Try it") está na **[referência gerada da API](/desenvolvedores/rest-api/nfse-inbound-v2)**.

> **Base URL:** `https://api.nfse.io` · **Auth:** API Key (papel `Nota Fiscal` ou `NFSeDist`; papel `Management` para os endpoints de manutenção, **exceto `fetch-now`**, que também é acessível pela própria empresa) — veja [Autenticação](../../comum/autenticacao.md).

## 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 ⚠️ (ver aviso de cobrança) |

## 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

| Método | Path | Auth | Propósito |
|---|---|---|---|
| `POST` | `.../inbound/nfse/maintenance/fetch-now` | `NFSeDist` **ou** `Management` | Força captura imediata da própria empresa (escopado ao *tenant*) |
| `GET` | `.../inbound/nfse/maintenance/notifications` | `Management` | Notificações operacionais |
| `GET` | `.../inbound/nfse/maintenance/statistics` | `Management` | Estatísticas operacionais |
| `POST` | `.../inbound/nfse/maintenance/reactivate` | `Management` | Reativa empresa desativada |

:::danger Risco de novas cobranças ao alterar o NSU
Tanto `POST .../reset-nsu` quanto o `fetch-now` com **`forcedStartNsu`** reposicionam o cursor de NSU. Um NSU **menor** que o `currentNsu` **re-captura documentos já processados e cada um é COBRADO NOVAMENTE** (bilhetagem por documento). Só reposicione o NSU quando souber exatamente o efeito. Veja [Manutenção administrativa](../how-to/manutencao-administrativa.md).
:::

## Exemplo de detalhe de documento

Resposta real (anonimizada) de `GET .../inbound/nfse/{id}`:

```json
{
  "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.
>
> **`substituteAccessKey`** vem preenchido apenas quando a NFS-e substitui outra nota (substituição/cancelamento com substituta); `null` caso 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) e `cityServiceCode` (código do município) — ver [Eventos de Webhook](./webhook-events.md).

## Veja também

- [Referência completa da API](/desenvolvedores/rest-api/nfse-inbound-v2)
- [Tipos e enums](./tipos-e-enums.md) · [Erros HTTP](./http-errors.md)