FAQ — NFS-e Inbound
Preciso de certificado digital para receber NFS-e?
Sim. A recepção de NFS-e acessa o ADN usando o certificado da empresa via mTLS — sem certificado válido, a captura é desativada (deactivationReason de certificado). Veja Certificado digital.
Como sou notificado de cada NFS-e?
Por webhook (POST assinado com HMAC-SHA1, header x-hub-signature). Veja Webhook — eventos.
Qual o tamanho da chave de acesso da NFS-e?
50 dígitos (modelo 56). O DPS tem 42 dígitos. Veja NSU, chaves e modelos.
Como manifesto como tomador?
Pelos códigos 203202 (Confirmação) e 203206 (Rejeição), de forma assíncrona (202). Veja Manifestação do tomador.
Já tenho a chave de acesso de uma nota, mas ela não apareceu. Consigo puxá-la agora?
Sim — POST .../inbound/nfse/fetch-by-access-key consulta a nota individualmente na SEFIN e devolve o documento na própria resposta. A SEFIN só entrega se o certificado da sua empresa aparecer na nota como Prestador, Tomador ou Intermediário (senão, 403), e a captura sob demanda tem SKU próprio de bilhetagem. Veja Captura sob demanda.
Como exporto muitos documentos de uma vez?
Use a exportação em massa (XML, PDF ou CSV) por período.
Como sei em qual versão de payload minha empresa está?
O webhookVersion não é exposto na API. Trate pela forma do payload recebido (empresas novas nascem em v2) ou confirme com o suporte. Veja Versionamento de webhook.
Preciso pagar por cada documento recebido?
A recepção de NFS-e é bilhetada por ação, dentro do mesmo recurso (ServiceInvoiceInbound). O serviço registra ações distintas para cada situação — captura de nota recebida, captura de nota emitida (outboundEnabled), documento retido pela data de corte, entrega do histórico liberado, captura sob demanda pela chave, consultas de XML/PDF e manifestação — justamente para que possam ser precificadas separadamente.
Quanto cada ação custa, e quais são gratuitas, está no seu plano comercial. Uma nota buscada sob demanda e depois trazida pelo lote gera registro nas duas ocasiões — se isso resulta em cobrança dupla é uma questão de precificação, não do serviço.
Onde há garantia técnica de não duplicar, ela está documentada no endpoint correspondente (por exemplo: repetir a captura sob demanda da mesma chave não refaz a consulta à SEFIN).
Documentos emitidos antes da ativação aparecem?
Para NF-e/CT-e, a SEFAZ disponibiliza ~90 dias de histórico (use startFromNsu/startFromDate).
Para NFS-e, a consulta ao ambiente nacional parte do início e devolve todo o histórico do CNPJ. Use o campo startFromDate no cadastro da empresa para definir a partir de quando você quer receber: documentos anteriores ao corte continuam capturados, mas não aparecem na listagem, não disparam webhook e são cobrados à parte como histórico. Veja Ativar via API.
Sem startFromDate, todo o histórico é tratado como documento corrente — notificado por webhook e cobrado como tal.
O webhookStatus do documento está Skipped. Meu endpoint falhou?
Não. Skipped significa que nenhuma entrega é devida para aquele documento: ele é anterior à data de corte (startFromDate) da empresa e está retido como histórico. Não é falha de entrega e não há o que corrigir no seu endpoint. Veja Tipos e enums.
Recebo as notas que a minha própria empresa emitiu?
Não por padrão. A captura entrega apenas as NFS-e em que a sua empresa é tomadora. Para receber também as emitidas, envie outboundEnabled: true no cadastro ou na atualização — veja Ativar via API.
Listagem em lote: há custo, limite de requisições ou ordenação fixa?
A listagem segue paginação por NSU em ordem ascendente. Para grandes volumes, prefira a exportação em massa (job assíncrono) em vez de paginar manualmente. Documentos que chegarem durante a iteração entram com NSU maior — continue do último NSU lido.
Qual a diferença entre NFS-e e NF-e?
NF-e (modelo 55) documenta mercadorias/produtos; NFS-e (modelo 56) documenta serviços. São produtos de recepção distintos — veja a visão geral.