DF-e

Distribuição POST

Consulta a SEFAZ (ou ADN, no caso de NFS-e) por documentos fiscais emitidos contra o CNPJ/CPF do seu contribuinte -- ele como destinatário/interessado, não como emitente. É assim que seu ERP fica sabendo de uma NF-e/CT-e/MDF-e/NFS-e que um fornecedor emitiu pra você, sem precisar que ele te avise manualmente.

⚠️

NF-e/CT-e/MDF-e só sincronizam em homologação hoje. Chamar em produção devolve 400 explícito, com detail vindo como objeto ({"codigo": "Nfe.Distribution.ProductionBlocked", "mensagem": "..."} -- troque Nfe por Cte/Mdfe conforme o documento) -- é uma trava deliberada desta fase do projeto, não um bug. NFS-e é a exceção -- sincroniza em produção normalmente, contrato real com o Ambiente Nacional já confirmado.

Endpoint (um por documento)

Documento	Endpoint	Ambiente
NF-e	`POST /v1/nfe/distribuicao/sincronizar`	Só homologação
CT-e	`POST /v1/cte/distribuicao/sincronizar`	Só homologação
MDF-e	`POST /v1/mdfe/distribuicao/sincronizar`	Só homologação
NFS-e	`POST /v1/nfse/distribuicao/sincronizar`	Homologação e produção

Corpo da requisição

Campo	Obrigatório	Observação
`contribuinte_documento`	Um dos dois	CNPJ/CPF do contribuinte interessado (destinatário dos documentos).
`contribuinte_id`	Um dos dois	UUID do contribuinte -- alternativa ao documento.

curl -X POST https://areacliente.centralfiscal.com.br/v1/nfe/distribuicao/sincronizar \
  -H "Authorization: Bearer cf_test_51JqK..." \
  -H "Content-Type: application/json" \
  -d '{"contribuinte_documento": "12345678000190"}'

Resposta

Cada chamada processa uma página (até 50 documentos) -- se tem_mais_documentos vier true, chame de novo pra continuar. Não existe hoje um job automático que faça isso por você (ver Automatizando abaixo).

{
  "ambiente": "HOMOLOGATION",
  "sucesso": true,
  "cstat": "138",
  "xmotivo": "Documento(s) localizado(s)",
  "documentos_recebidos": 3,
  "documentos_novos": 2,
  "ultimo_nsu": "000000000000045",
  "tem_mais_documentos": false,
  "mensagem": "Documento(s) localizado(s)",
  "avisos": []
}

💡

cstat 137 ("Nenhum documento localizado") é sucesso, não erro -- significa que não tem nada novo desde a última sincronização. documentos_novos pode ser menor que documentos_recebidos quando o mesmo NSU já tinha sido processado antes (idempotente).

Automatizando

⚠️

Hoje esta é uma chamada sob demanda -- não existe agendamento automático nosso disparando isso periodicamente. Se seu ERP precisa ficar atualizado continuamente, é você quem decide a cadência e chama este endpoint num cron/job próprio (respeitando o rate-limit real da SEFAZ, que costuma aplicar cooldown de cerca de 1 hora quando uma consulta volta vazia).

Depois de sincronizar, os documentos já baixados ficam disponíveis em Consulta -- sem precisar chamar a SEFAZ de novo.