Skip to main content
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.

​
Como funciona

A distribuição da SEFAZ entrega a nota em duas etapas, e é por isso que toda nota recebida tem um campo isComplete: 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. 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:
PUT /v1/companies/{id}/settings
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.

​
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:
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).

​
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

Manifestação do destinatário

Dar ciência, confirmar ou recusar uma nota — e liberar o XML completo.

NFS-e tomadas

Notas de serviço tomadas pela sua empresa, entregues completas desde a importação.

Eventos e payload

Ser notificado quando uma nota é detectada ou completada.