---
title: "Ativar a captura de NFS-e via API"
description: "Como cadastrar, consultar, atualizar e desativar a captura automática de NFS-e de uma empresa pela API REST."
source_url: https://nfe.io/docs/distribuicao-nfse-inbound-ativar-api/
last_updated: 2026-07-30
---

# Ativar a captura de NFS-e via API

Para receber automaticamente as NFS-e emitidas contra o CNPJ da sua empresa, cadastre-a no serviço de recepção. Todas as rotas exigem uma API Key com papel `Nota Fiscal (api.nfe.io)` ou `NFSeDist (dfe.nfe.io)` — veja [Autenticação](../../comum/autenticacao.md).

> **Base URL:** `https://api.nfse.io`

## Cadastrar a empresa

```bash
curl -X POST "https://api.nfse.io/v2/companies/inbound/nfse" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "SEU_COMPANY_ID",
    "initialNsu": 0,
    "webhookUrl": "https://seu-sistema.com/webhooks/nfse"
  }'
```

`initialNsu` é **obrigatório** (use `0` para capturar desde o início disponível). Resposta `201 Created`. Se a empresa já estiver cadastrada, a API retorna `409 Conflict`.

O campo `environment` é **opcional**. Aceita `"Production"`, `"Development"` ou `"Homologation"` (case-insensitive). Quando omitido, herda o ambiente da inscrição municipal (TaxPayers); se ausente também ali, assume `"Production"` por padrão.

## Consultar a configuração

```bash
curl "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/details" \
  -H "Authorization: SUA_API_KEY"
```

Retorna a configuração atual: `webhookUrl`, `isActive`, `currentNsu`, `environment`, `isAutomaticManifestationEnabled`, etc. O `webhookVersion` **não** é exposto na resposta (veja [Versionamento de webhook](../reference/versionamento-webhook.md)).

## Atualizar a configuração

```bash
curl -X PUT "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/details" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://seu-sistema.com/webhooks/nfse",
    "isAutomaticManifestationEnabled": true,
    "automaticManifestationDelaySeconds": 3600,
    "isActive": true
  }'
```

- `automaticManifestationDelaySeconds` aceita de `0` a `604800` (7 dias).

## Desativar

```bash
curl -X DELETE "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/details" \
  -H "Authorization: SUA_API_KEY"
```

A captura para, mas os documentos já recebidos continuam acessíveis.

## Redefinir o cursor (reset-nsu)

Para reprocessar a partir de um NSU específico:

```bash
curl -X POST "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/reset-nsu" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nsu": 0 }'
```

## Veja também

- [Integração REST](./integracao-rest.md)
- [Ativar via painel](./ativar-via-painel.md)
- [Referência da API NFS-e Inbound](/desenvolvedores/rest-api/nfse-inbound-v2)