Capturar uma NFS-e sob demanda pela chave de acesso
POST/v2/companies/:companyId/inbound/nfse/fetch-by-access-key
Consulta individual sincrona a SEFIN Nacional (GET /nfse/{chave})
para capturar uma NFS-e especifica que o lote ADN ainda nao distribuiu.
O documento e persistido e devolvido na propria resposta.
Sigilo fiscal: a SEFIN so devolve o conteudo quando o certificado da
empresa aparece na nota como Prestador, Tomador ou Intermediario. Caso
contrario, 403 com error: AccessForbidden.
Idempotencia: se a NFS-e ja foi capturada (por lote ou por outra
chamada sob demanda), retorna 200 OK com o documento existente, sem
rebuscar na SEFIN — nao duplica documento nem gera trafego extra contra
o ambiente nacional. A chamada em si continua sendo registrada como uso.
nsu nulo: documentos capturados por aqui nascem com nsu: null —
o NSU e atribuido pela distribuicao em lote. Quando o lote trouxer a
mesma NFS-e, o nsu e preenchido e o webhook dispara normalmente.
Uso/bilhetagem: toda chamada grava um registro de uso sob a acao
GetDocByKey — inclusive as idempotentes, que no registro sao
indistinguiveis de uma captura nova. Quando o lote trouxer a mesma
NFS-e, essa chegada grava o registro normal de captura (ProcessDoc).
A precificacao de cada acao e definida no plano comercial.
webhookStatus nasce Delivered sem POST algum: esta via nao publica
webhook — os dados ja vao na resposta. Gravar como entregue evita deixar
uma entrega pendente que nunca aconteceria. Quando o lote trouxer a mesma
NFS-e, o status de entrega e reiniciado e o webhook e despachado.
Request
Responses
- 200
- 400
- 403
- 404
- 502
- 503
Documento capturado agora, ou o existente (idempotente).
InvalidAccessKey — chave ausente, fora do formato de 50 digitos ou com digito verificador invalido.
AccessForbidden — sigilo fiscal: a empresa nao e Prestador, Tomador nem Intermediario da nota.
CompanyNotFound, CertificateUnavailable ou AdnNotFound. AdnNotFound tambem e retornado quando o documento JA foi capturado e esta retido como historico (anterior ao corte, liberacao nao contratada) — mesmo desfecho de chave desconhecida, de proposito. Uma nota anterior ao corte que ainda NAO foi capturada e capturada normalmente por este endpoint e nao nasce historica.
CertificateRejected — a SEFIN rejeitou o certificado da empresa.
AdnUnavailable (SEFIN fora) ou CertificateLookupFailed (falhou a consulta ao certificado — nao se sabe se existe; retente).