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

​
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, e ela altera o desenho da integração. 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.
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.

​
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.
  3. A importação ativada na empresa, com a data a partir da qual importar:
PUT /v1/companies/{id}/settings
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.
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:
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:
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).

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

​
Webhooks

A NFS-e tomada dispara dois dos três eventos de nota recebida: 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.

​
Próximos passos

Manifestação do tomador

Confirmar ou rejeitar uma NFS-e tomada, e o caráter definitivo da decisão.

Eventos e payload

Ser notificado quando uma nota é importada ou recebe um evento.