> ## 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
> NF-e emitidas contra o CNPJ da sua empresa: como a Spedy busca na distribuição da SEFAZ e como habilitar o recurso.
Além de **emitir** documentos fiscais, a Spedy busca automaticamente as notas
que **terceiros emitiram contra o CNPJ da sua empresa** — as **notas
recebidas**. São as NF-e em que a sua empresa aparece como **destinatária**:
compras de fornecedores, devoluções, transferências, remessas.
A SEFAZ mantém um serviço de **distribuição** que entrega esses documentos ao
destinatário. A Spedy consulta esse serviço por você, guarda cada nota e
notifica sua integração — você não precisa pedir a chave de acesso ao emissor
nem monitorar a SEFAZ manualmente.
Esta página trata das **NF-e recebidas** (produto). As **NFS-e tomadas**
(serviço) seguem um caminho próprio, com regras diferentes de manifestação e
de disponibilidade do XML — veja
[NFS-e tomadas](/guides/notas-recebidas/nfse/visao-geral).
## Como funciona
```mermaid theme={null}
graph TD
Emitente["Fornecedor emite NF-e
contra o seu CNPJ"]
Sefaz["Distribuição da SEFAZ"]
Spedy["Spedy busca
(automático + sob demanda)"]
Resumo["Nota recebida
como RESUMO"]
Manifest["Você manifesta"]
Completo["XML autorizado
COMPLETO + DANFE"]
Emitente --> Sefaz
Sefaz --> Spedy
Spedy --> Resumo
Resumo -->|inbound_invoice.detected| Manifest
Manifest -->|inbound_invoice.completed| Completo
```
A distribuição da SEFAZ entrega a nota em **duas etapas**, e é por isso que
toda nota recebida tem um campo **`isComplete`**:
| Etapa | `isComplete` | O que você tem | Serve para |
| ------------ | ------------ | ---------------------------------------------------------------------- | -------------------------------------------- |
| **Resumo** | `false` | Dados essenciais enviados pela SEFAZ (emissor, valor, chave, situação) | Conferência, triagem, decidir a manifestação |
| **Completo** | `true` | XML autorizado integral + DANFE em PDF | Escrituração fiscal e contábil |
O resumo chega sozinho, assim que a nota é distribuída. O **XML completo** só é
liberado pela SEFAZ **depois que você manifesta** a nota — veja
[Manifestação do destinatário](/guides/notas-recebidas/nfe/manifestacao).
Antes disso, o download de XML traz apenas o resumo (que **não vale** para
escrituração) e o DANFE ainda não está disponível.
## Habilitar o recurso
O recebimento é **opcional** e depende de duas coisas:
1. **O recurso no seu plano.** As notas recebidas exigem o recurso
`inbound_invoices`. Sem ele, os endpoints respondem `403`. Fale com a Spedy
se o seu plano ainda não o inclui.
2. **Ativar a importação na empresa.** Ligue a busca automática nas
configurações da empresa, informando a partir de qual data importar:
```json PUT /v1/companies/{id}/settings theme={null}
{
"productInvoice": {
"inbound": {
"enabled": true,
"startDate": "2026-01-01"
}
}
}
```
`startDate` define o ponto de corte: só 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, e a
própria SEFAZ retém cerca de 90 dias de histórico na distribuição. Se você
habilitar sem informar a data, a Spedy assume a data de hoje.
A busca usa o **certificado digital** da empresa (o mesmo da emissão) para se
autenticar na SEFAZ — garanta que ele esteja válido. Veja
[Certificado digital](/guides/certificado-digital).
## Buscar automaticamente e sob demanda
Com o recurso ativo, a Spedy consulta a distribuição da SEFAZ **periodicamente**
por conta própria — você não precisa fazer nada para as notas chegarem. Para
**antecipar** uma busca (por exemplo, quando você sabe que uma nota acabou de
ser emitida), há o endpoint de **sincronização sob demanda**:
```http theme={null}
POST /v1/inbound-product-invoices/sync
```
A sincronização é **assíncrona**: a resposta apenas confirma 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é
liberar) e, no corpo, `retryAfterSeconds` e `nextAllowedSyncAt`. Respeite o
`Retry-After` antes de tentar de novo.
Esse intervalo **não é uma regra arbitrária da Spedy**: a própria SEFAZ limita a
frequência de consultas à distribuição por CNPJ. Consultar em excesso é tratado
como **consumo indevido** e faz a SEFAZ **bloquear temporariamente o seu CNPJ**
para novas consultas. O `429` da Spedy espaça as chamadas justamente para manter
o seu CNPJ dentro do limite da SEFAZ e evitar esse bloqueio — por isso respeitar
o `Retry-After` é do seu interesse, não só uma formalidade.
Não fique repetindo o `sync` para descobrir se chegou nota nova — você vai
esbarrar no `429`. Para ser avisado quando notas chegarem, **assine os
webhooks** `inbound_invoice.detected` e `inbound_invoice.completed` (veja
[Eventos e payload](/webhooks/eventos-e-payload)).
## Listar e paginar
A listagem (`GET /v1/inbound-product-invoices`) traz as notas da mais recente
para a mais antiga e aceita filtros por período (`initialDate`/`endDate`),
situação (`status`), status de manifestação (`manifestationStatus`), ambiente e
chave de acesso.
A paginação é **por cursor**: cada resposta traz um `nextCursor`; envie-o no
parâmetro `cursor` da próxima chamada para obter a página seguinte. Quando
`nextCursor` vier **nulo**, não há mais páginas. Não interprete o conteúdo do
cursor — o formato pode mudar sem aviso.
## Próximos passos
Dar ciência, confirmar ou recusar uma nota — e liberar o XML completo.
Notas de serviço tomadas pela sua empresa, entregues completas desde a importação.
Ser notificado quando uma nota é detectada ou completada.