> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral

> NFS-e tomadas pela sua empresa: como a Spedy importa do Ambiente de Dados Nacional, o que é entregue e como habilitar.

Além de **emitir** documentos fiscais, a Spedy importa automaticamente as
**NFS-e emitidas contra o CNPJ da sua empresa** — as notas de serviço tomadas.

A importação é feita pelo **Ambiente de Dados Nacional (ADN)** do Sistema
Nacional NFS-e, que concentra os documentos dos municípios e os distribui a quem
figura neles. A Spedy consulta esse serviço, armazena cada nota e notifica a sua
integração, sem que seja necessário solicitar o XML ao prestador ou acompanhar
portais municipais.

## Escopo da importação

São importadas as notas em que a sua empresa figura como **tomadora** do serviço
ou como **intermediária** da operação. O campo `role` identifica o papel:

| `role`         | Papel da sua empresa      |
| -------------- | ------------------------- |
| `recipient`    | Tomadora do serviço       |
| `intermediary` | Intermediária da operação |

O ambiente nacional entrega ao CNPJ todos os documentos em que ele aparece,
inclusive as notas emitidas pela própria empresa como prestadora. Essas são
descartadas na importação: já constam na conta como notas emitidas, e importá-las
duplicaria o mesmo documento. Para consultá-las, use
`GET /v1/service-invoices`.

<Note>
  A distribuição alcança as notas dos **municípios que compartilham seus
  documentos com o ambiente nacional**. Documentos de municípios fora desse
  compartilhamento não são distribuídos por este canal.
</Note>

## Documento completo desde a importação

A NFS-e é entregue completa pelo ambiente nacional, sem etapa de resumo. Esta é a
principal diferença em relação à
[NF-e recebida](/guides/notas-recebidas/nfe/visao-geral), e ela altera o desenho
da integração.

```mermaid theme={null}
graph TD
  Prestador["Prestador emite NFS-e<br/>contra o seu CNPJ"]
  Adn["Ambiente de Dados Nacional"]
  Spedy["Spedy importa<br/>(automático + sob demanda)"]
  Completa["Nota recebida COMPLETA<br/>XML + DANFSe disponíveis"]
  Manifest["Manifestação<br/>(opcional, definitiva)"]

  Prestador --> Adn
  Adn --> Spedy
  Spedy --> Completa
  Completa -->|inbound_invoice.detected| Manifest
```

|                             | NF-e recebida       | NFS-e tomada                   |
| --------------------------- | ------------------- | ------------------------------ |
| `isComplete` na chegada     | `false` (resumo)    | **sempre `true`**              |
| XML autorizado              | após a manifestação | **desde a importação**         |
| DANFE / DANFSe              | após a manifestação | **desde a importação**         |
| Função da manifestação      | liberar o XML       | registrar a posição do tomador |
| `inbound_invoice.completed` | disparado           | **não disparado**              |

O campo `isComplete` permanece no contrato e é sempre verdadeiro na NFS-e.
Integrações que condicionam o download do XML a esse campo continuam válidas sem
alteração.

<Warning>
  `inbound_invoice.completed` não é disparado para NFS-e. O evento anuncia a
  transição de resumo para documento completo, que não ocorre neste modelo.
  Utilize `inbound_invoice.detected` como gatilho.
</Warning>

## Habilitar o recurso

O recebimento é opcional e depende de três condições:

1. **O recurso no plano.** As notas recebidas exigem o recurso
   `inbound_invoices`. Sem ele, os endpoints respondem `403`. O recurso é o
   mesmo para NF-e e NFS-e.
2. **Certificado digital A1 válido na empresa.** O acesso ao ambiente nacional é
   autenticado pelo certificado; sem um certificado válido cadastrado, a
   habilitação é recusada. O requisito costuma exigir atenção nas empresas que
   emitem NFS-e por usuário e senha do município e não mantêm certificado
   cadastrado. Veja [Certificado digital](/guides/certificado-digital).
3. **A importação ativada na empresa**, com a data a partir da qual importar:

```json PUT /v1/companies/{id}/settings theme={null}
{
  "serviceInvoice": {
    "inbound": {
      "enabled": true,
      "startDate": "2026-08-01"
    }
  }
}
```

<Note>
  `startDate` é a **data de corte**: apenas notas emitidas a partir dela são
  importadas; as anteriores são descartadas. A data **não pode ser anterior a 90
  dias** daquela em que é informada — valores mais antigos são recusados. Ao
  habilitar sem informar a data, vale **a partir de hoje**.
</Note>

O ambiente nacional não descarta histórico. Sem a data de corte, a primeira
sincronização importaria toda a fila acumulada desde a adesão do município, o
que pode representar um volume elevado de notas.

## Ambiente

A importação ocorre **sempre em produção**, independentemente do ambiente
configurado para a emissão da empresa. O ambiente nacional não distribui
documentos reais em homologação; vincular a importação ao ambiente de emissão
faria com que uma empresa em homologação não recebesse nenhuma nota.

## Sincronização

Com o recurso ativo, a Spedy consulta a distribuição do ambiente nacional
periodicamente. A chegada das notas não depende de nenhuma ação da sua
integração.

Para antecipar uma busca, use a sincronização sob demanda:

```http theme={null}
POST /v1/inbound-service-invoices/sync
```

A sincronização é **assíncrona**: a resposta confirma apenas que o pedido foi
aceito. Há um intervalo mínimo entre chamadas — dentro dele a resposta é
**`429 Too Many Requests`**, com o cabeçalho `Retry-After` (segundos até a
liberação) e, no corpo, `retryAfterSeconds` e `nextAllowedSyncAt`.

O intervalo decorre de uma restrição do próprio ambiente nacional, que impõe
espera mínima entre consultas por CNPJ e trata a consulta em excesso como
consumo indevido. Respeitar o `Retry-After` mantém o CNPJ dentro desse limite.

Para consultar a última sincronização e o momento a partir do qual uma nova é
permitida:

```http theme={null}
GET /v1/inbound-service-invoices/sync-status
```

<Warning>
  Não utilize o `sync` como mecanismo de verificação periódica: chamadas
  repetidas resultam em `429`. Para ser notificado da chegada de notas, assine os
  webhooks (veja [Eventos e payload](/webhooks/eventos-e-payload)).
</Warning>

### Consulta por chave de acesso

A NFS-e não dispõe de consulta pontual por chave de acesso. As notas chegam
exclusivamente pela distribuição. O endpoint de atualização individual
(`/refresh`) existe apenas para a NF-e, onde serve para obter na SEFAZ o XML
completo de uma nota específica — necessidade que não se aplica à NFS-e, entregue
completa desde a importação.

## Listagem e paginação

A listagem (`GET /v1/inbound-service-invoices`) retorna as notas da mais recente
para a mais antiga e aceita os filtros:

| Filtro                    | Valores                                             |
| ------------------------- | --------------------------------------------------- |
| `accessKey`               | Chave de acesso da NFS-e (**50 dígitos**)           |
| `status`                  | `authorized`, `canceled` — aceita múltiplos valores |
| `manifestationStatus`     | `none`, `confirmed`, `rejected`                     |
| `role`                    | `recipient`, `intermediary`                         |
| `initialDate` / `endDate` | Período de emissão (inclusive)                      |
| `environmentType`         | Ambiente das notas                                  |

<Note>
  A chave da NFS-e tem **50 dígitos**, contra os 44 da NF-e — os leiautes são
  distintos. Campos de tamanho fixo dimensionados para a chave da NF-e precisam
  ser ajustados.
</Note>

A paginação é **por cursor**: cada resposta traz um `nextCursor`, que deve ser
enviado no parâmetro `cursor` da chamada seguinte para obter a próxima página.
Quando `nextCursor` vier **nulo**, não há mais páginas. O conteúdo do cursor não
deve ser interpretado — o formato pode mudar sem aviso.

## XML e DANFSe

Ambos ficam disponíveis assim que a nota é importada, sem depender de
manifestação:

```http theme={null}
GET /v1/inbound-service-invoices/{id}/xml
GET /v1/inbound-service-invoices/{id}/pdf
```

O `/xml` retorna o XML nacional da nota, válido para escrituração. O `/pdf` gera
o **DANFSe** a partir desse XML.

## Eventos da nota

Além da nota, a Spedy vincula a ela os eventos distribuídos pelo ambiente
nacional. Cada um dispara o webhook `inbound_invoice.event` e consta em `events`
no detalhe da nota.

| `type`          | Significado                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancellation`  | Cancelamento da nota — pelo prestador, por substituição, por deferimento de análise fiscal ou por ofício. A situação da nota passa a `canceled`                                                                                                                   |
| `manifestation` | Manifestação do tomador registrada: a Confirmação ou a Rejeição enviada pela sua empresa, ou a **confirmação tácita** emitida pela administração por decurso de prazo                                                                                             |
| `other`         | Demais eventos do padrão nacional vinculados ao histórico — manifestações do prestador e do intermediário, solicitação e indeferimento de análise fiscal de cancelamento, anulação de rejeição, bloqueio e desbloqueio por ofício. Não alteram a situação da nota |

O código fiscal original do evento é retornado em `eventCode` e a descrição em
`description`, para os casos em que o detalhe exato dentro de cada tipo for
necessário.

<Note>
  A **confirmação tácita** é registrada pela administração por decurso de prazo,
  sem ação do tomador. Quando ela ocorre, `manifestation.status` da nota passa a
  `confirmed`.
</Note>

## Webhooks

A NFS-e tomada dispara dois dos três eventos de nota recebida:

| Evento                      | Disparado na NFS-e                      |
| --------------------------- | --------------------------------------- |
| `inbound_invoice.detected`  | **Sim** — nota nova importada           |
| `inbound_invoice.event`     | **Sim** — evento vinculado à nota       |
| `inbound_invoice.completed` | **Não** — a nota já é entregue completa |

Os três tipos são **compartilhados com a NF-e**. O campo **`model`** do payload
identifica o modelo recebido: `serviceInvoice` para NFS-e, `productInvoice` para
NF-e. Veja [Eventos e payload](/webhooks/eventos-e-payload).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Manifestação do tomador" icon="reply" href="/guides/notas-recebidas/nfse/manifestacao">
    Confirmar ou rejeitar uma NFS-e tomada, e o caráter definitivo da decisão.
  </Card>

  <Card title="Eventos e payload" icon="bell" href="/webhooks/eventos-e-payload">
    Ser notificado quando uma nota é importada ou recebe um evento.
  </Card>
</CardGroup>