Documentos recebidos e DistDFe

Nota

Manifestação do Destinatário

A Manifestação do Destinatário permite que o destinatário de uma NF-e se posicione formalmente sobre uma nota fiscal emitida contra seu CNPJ. São 4 tipos de eventos previstos pelo Fisco, todos com base legal definida.

Tipos de Evento

Código	Nome	Significado	Justificativa
210210	Ciência da Operação	O destinatário tomou conhecimento da NF-e, mas ainda não confirmou nem rejeitou. Geralmente o primeiro evento dado, requisito para baixar o XML completo via DistDFe.	Não obrigatória
210200	Confirmação da Operação	O destinatário confirma que a operação aconteceu e a mercadoria/serviço foi recebida. Evento final, comprova recebimento.	Não obrigatória
210220	Desconhecimento da Operação	O destinatário declara que NÃO reconhece a operação (suspeita de fraude, uso indevido do CNPJ, etc).	Obrigatória (15-255 chars)
210240	Operação Não Realizada	O destinatário reconhece a operação mas declara que ela NÃO se concretizou (devolução, recusa de recebimento, etc).	Obrigatória (15-255 chars)

Regra de sequência: Após dar Ciência (210210), pode-se enviar Confirmação (210200) OU Desconhecimento (210220) OU Não Realizada (210240). Confirmação/Desconhecimento/Não Realizada são estados finais — não podem ser sobrepostos.

Atenção: O CNPJ enviado no campo cnpj deve ser o do destinatário da NF-e (quem está manifestando) e deve estar cadastrado no sistema vinculado ao token usado. Caso contrário o Fisco retorna a rejeição "O autor do evento diverge do destinatário da NF-e".

Códigos cStat de Retorno

cStat	Significado
135	✅ Evento registrado com sucesso
573	✅ Duplicidade de evento — já registrado anteriormente (tratado como sucesso)
236	❌ Chave de acesso inválida
491	❌ Manifestação já registrada — não pode sobrescrever estado final
596	❌ CNPJ destinatário diverge do informado
656	❌ Consumo indevido (rate limit)

POST/api/invoice/manifest

Enviar evento de manifestação do destinatário

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
chave	string	Sim	Chave de acesso da NF-e — 44 dígitos
cnpj	string	Sim	CNPJ do destinatário (quem manifesta) — 14 dígitos, sem formatação. Deve estar cadastrado no sistema
tipo_evento	int	Sim	Código do evento: `210200`, `210210`, `210220` ou `210240`
justificativa	string	Condicional	Obrigatória para `210220` e `210240`. Deve ter entre 15 e 255 caracteres. Ignorada para `210200` e `210210`

Sequência (nSeqEvento): calculada automaticamente. Para a mesma combinação (cnpj + chave + tipo_evento) é incrementada a cada chamada — assim duplicatas retornam cStat: 573 e são gravadas sem erro.

Campos da Resposta

Campo	Tipo	Descrição
id	string	ObjectId interno do registro da manifestação (usado em `/get_xml`)
chave	string	Chave de acesso da NF-e manifestada
cnpj	string	CNPJ do destinatário que manifestou
tipo_evento	int	Código do evento enviado (210200/210210/210220/210240)
desc_evento	string	Descrição textual do evento
nProt	string	Número do protocolo Fisco — comprovante do evento
cStat	int	Código de status Fisco. `135` = registrado, `573` = duplicidade (também aceito)
xMotivo	string	Mensagem descritiva do retorno Fisco
nSeqEvento	int	Sequência do evento atribuída automaticamente
xml_url	string	URL pública do XML do procEvento (assinado e protocolado) armazenado no OSS

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/manifest" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "chave": "35260514200166000187550010000000011000000018",
          "cnpj": "14200166000187",
          "tipo_evento": 210210,
          "justificativa": "Operação reconhecida pelo destinatário"
        }

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "67341a8f5d4e1f2a3b4c5d6e",
            "chave": "35260514200166000187550010000000011000000018",
            "cnpj": "14200166000187",
            "tipo_evento": 210210,
            "desc_evento": "Ciencia da Operacao",
            "nProt": "135260000123456",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a NF-e",
            "nSeqEvento": 1,
            "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
          }
        }

        {
          "chave": "35260514200166000187550010000000011000000018",
          "cnpj": "14200166000187",
          "tipo_evento": 210220,
          "justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
        }

POST/api/invoice/manifest/list

Listar manifestações

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
cnpj	string	Não	Filtra por CNPJ do destinatário. Se omitido, lista de todos os CNPJs do usuário
chave	string	Não	Filtra por chave NF-e específica (44 dígitos)
start_create_time	string/long	Não	Data inicial da criação. Aceita formatos: `"dd/MM/yyyy"`, `"yyyy-MM-dd"`, `"dd/MM/yyyy HH:mm:ss"` ou Unix timestamp em segundos. Considera 00:00:00 UTC se só data
end_create_time	string/long	Não	Data final da criação. Mesmo formato. Se só data, considera 23:59:59.999 UTC
page	int	Não	Número da página (default `1`)
page_size	int	Não	Itens por página (default `20`, máximo `100`)

Campos da Resposta

Campo	Tipo	Descrição
total	int	Total de registros que atendem aos filtros (independente de paginação)
page	int	Página atual retornada
page_size	int	Tamanho da página retornada
list[].id	string	ObjectId interno do registro
list[].chave	string	Chave de acesso da NF-e manifestada
list[].cnpj	string	CNPJ destinatário que manifestou
list[].tipo_evento	int	Código do evento (210200/210210/210220/210240)
list[].desc_evento	string	Descrição textual do evento
list[].justificativa	string	Justificativa enviada (preenchido apenas para 210220/210240)
list[].nProt	string	Protocolo Fisco do evento
list[].nSeqEvento	int	Sequência do evento
list[].cStat	int	Código de status Fisco
list[].xMotivo	string	Mensagem descritiva do retorno Fisco
list[].xml_url	string	URL pública do XML do procEvento no OSS
list[].create	string	Data/hora UTC do registro (formato `yyyy-MM-dd HH:mm:ss`)

Ordenação: registros são retornados do mais recente para o mais antigo (por create decrescente).

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/manifest/list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "cnpj": "14200166000187",
          "chave": "",
          "start_create_time": "01/05/2026",
          "end_create_time": "31/05/2026",
          "page": 1,
          "page_size": 20
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "total": 2,
            "page": 1,
            "page_size": 20,
            "list": [
              {
                "id": "67341a8f5d4e1f2a3b4c5d6e",
                "chave": "35260514200166000187550010000000011000000018",
                "cnpj": "14200166000187",
                "tipo_evento": 210210,
                "desc_evento": "Ciencia da Operacao",
                "justificativa": "Operação reconhecida pelo destinatário",
                "nProt": "135260000123456",
                "nSeqEvento": 1,
                "cStat": 135,
                "xMotivo": "Evento registrado e vinculado a NF-e",
                "xml_url": "https://storage.../...210210_1.xml",
                "create": "2026-05-13 14:25:33"
              }
            ]
          }
        }

POST/api/invoice/manifest/get_xml

Obter XML da manifestação

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ObjectId da manifestação — retornado em `/manifest` ou `/manifest/list`

Erros Comuns

Mensagem	Causa
id inválido	Valor não é um ObjectId válido
manifestação não encontrada	ObjectId existe mas não pertence ao usuário do token, ou foi excluído

Nota

Captura DistDFe — NFes Recebidas

Permite consultar e baixar NFes e eventos destinados ao seu CNPJ via o serviço NFeDistribuicaoDFe do Fisco (Ambiente Nacional). A captura é incremental por NSU (Número Sequencial Único) — cada chamada baixa apenas o que ainda não foi capturado anteriormente.

Tipos de Documento Retornados

doc_type	O que é	Conteúdo
resNFe	Resumo de NFe	Metadados básicos (chave, valor, emitente, situação). Vem ANTES da Ciência ser dada — não contém produtos/impostos
procNFe	NFe completa autorizada	XML completo da NFe (com produtos, impostos, transporte, etc). Só vem APÓS o destinatário dar Ciência (210210) na chave
resEvento	Resumo de evento	Metadados de evento (chave, tipo, sequência, motivo)
procEvento	Evento completo	XML completo do evento (CCe, cancelamento, manifestações de outros destinatários sobre suas notas)

Fluxo recomendado:

Chame /received/sync — baixa todos os documentos novos
Liste com /received/list filtrando por doc_type: "resNFe" para ver notas sem Ciência
Para cada chave de interesse, chame /invoice/manifest com tipo_evento: 210210
Chame /received/sync novamente — agora o Fisco devolve os procNFe (XML completo) das chaves manifestadas
Use /received/get_xml para obter a URL do XML e baixar/processar

Rate limit do Fisco: o Fisco permite no máximo 1 chamada DistDFe por hora por CNPJ. Se exceder, retorna cStat: 656 (Consumo Indevido). Em ambiente de homologação a regra é mais permissiva.

Códigos cStat de Retorno do DistDFe

cStat	Significado
137	✅ Nenhum documento localizado (fim normal do loop)
138	✅ Documentos localizados — loop continua
656	❌ Consumo indevido — aguardar 1h e tentar novamente
252	❌ Ambiente diferente do informado (produção vs homologação)
280	❌ Certificado expirado ou inválido

POST/api/invoice/received/sync

Sincronizar documentos recebidos

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
cnpj	string	Sim	CNPJ da empresa destinatária — 14 dígitos, sem formatação. Deve estar cadastrado no sistema vinculado ao token
max_iterations	int	Não	Número máximo de chamadas ao Fisco por execução. Cada chamada baixa até 50 documentos. Default `50` (≈2500 docs), máximo `200`

Como funciona:

Lê o último ultNSU persistido para esse (uid + cnpj)
Faz loop chamando o Fisco até cStat ≠ 138 ou atingir max_iterations
Descomprime os XMLs (gzip) retornados
Persiste cada documento em w_invoice_received com upload do XML no OSS
Atualiza ultNSU e maxNSU em w_invoice_received_sync
Deduplica por (uid + cnpj + nsu) — chamadas repetidas não duplicam

Campos da Resposta

Campo	Tipo	Descrição
cnpj	string	CNPJ destinatário consultado
uf	string	UF do destinatário usada na consulta
initial_nsu	long	NSU de partida — o último processado antes dessa execução
ult_nsu	long	Novo último NSU após a sincronização
max_nsu	long	Maior NSU disponível no Ambiente Nacional no momento da consulta
pending	long	Documentos ainda pendentes (`max_nsu - ult_nsu`). Se > 0, chame `/sync` novamente para baixar o restante
iterations	int	Quantas chamadas ao Fisco foram feitas nessa execução
last_cstat	int	Último cStat retornado pelo Fisco. `137` é fim normal, `656` é rate limit
last_motivo	string	Mensagem descritiva do último retorno Fisco
stats.resNFe	int	Quantidade de resumos de NFe baixados nessa execução
stats.procNFe	int	Quantidade de NFes completas baixadas
stats.resEvento	int	Quantidade de resumos de evento baixados
stats.procEvento	int	Quantidade de eventos completos baixados
stats.skipped	int	Documentos ignorados (duplicados ou erro de parsing isolado)

Volume inicial: empresas que nunca sincronizaram podem ter centenas a milhares de documentos históricos. A primeira execução pode demorar mais e ser interrompida pelo max_iterations. Verifique pending na resposta — se > 0, chame de novo (respeitando o rate limit).

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/received/sync" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "cnpj": "26638419000167",
          "max_iterations": 50
        }

        {
          "success": true,
          "message": "data",
          "data": {
            "cnpj": "26638419000167",
            "uf": "SP",
            "initial_nsu": 0,
            "ult_nsu": 2323,
            "max_nsu": 2323,
            "pending": 0,
            "iterations": 8,
            "last_cstat": 137,
            "last_motivo": "Nenhum documento localizado",
            "stats": {
              "resNFe": 3,
              "procNFe": 4,
              "resEvento": 336,
              "procEvento": 5,
              "skipped": 0
            }
          }
        }

POST/api/invoice/received/list

Listar documentos recebidos

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
cnpj	string	Não	Filtra por CNPJ destinatário (o seu CNPJ). Se omitido, lista de todos do usuário
doc_type	string	Não	Filtra por tipo de documento: `resNFe`, `procNFe`, `resEvento` ou `procEvento`
chave	string	Não	Filtra por chave de acesso (44 dígitos)
emitente_cnpj	string	Não	Filtra por CNPJ do emitente da NFe (fornecedor)
start_create_time	string/long	Não	Data inicial. Aceita `"dd/MM/yyyy"`, ISO ou Unix timestamp
end_create_time	string/long	Não	Data final. Mesmo formato
page	int	Não	Número da página (default `1`)
page_size	int	Não	Itens por página (default `20`, máximo `100`)

Campos da Resposta

Campo	Tipo	Descrição
total	int	Total de registros que atendem aos filtros
page	int	Página atual
page_size	int	Tamanho da página
list[].id	string	ObjectId interno (use em `/received/get_xml`)
list[].nsu	long	NSU atribuído pelo Fisco a este documento
list[].doc_type	string	Tipo do documento: `resNFe`, `procNFe`, `resEvento`, `procEvento`
list[].schema	string	Schema do documento (ex: `resNFe_v1.01.xsd`)
list[].chave	string	Chave de acesso da NF-e (44 dígitos)
list[].cnpj_destinatario	string	CNPJ destinatário (o seu CNPJ)
list[].emitente_cnpj	string	CNPJ do emitente da NFe (fornecedor)
list[].emitente_nome	string	Razão social do emitente
list[].valor	decimal	Valor total da NFe (`vNF`)
list[].dh_emi	string	Data/hora de emissão da NFe
list[].serie	int	Série da NFe (preenchido apenas em `procNFe`)
list[].number	long	Número da NFe (preenchido apenas em `procNFe`)
list[].tp_nf	int	Tipo da operação: `0`=Entrada, `1`=Saída (na ótica do emitente)
list[].c_sit_nfe	int	Situação da NFe (preenchido em `resNFe`): `1`=Autorizada, `2`=Denegada, `3`=Cancelada
list[].tp_evento	int	Código do evento (preenchido em `resEvento`/`procEvento`). Ex: `110110`=CCe, `110111`=Cancelamento, `210210`=Ciência
list[].desc_evento	string	Descrição textual do evento
list[].n_seq_evento	int	Sequência do evento
list[].dh_evento	string	Data/hora do evento (eventos)
list[].xml_url	string	URL pública do XML do documento no OSS
list[].create	string	Data/hora UTC da captura

Ordenação: registros são retornados por NSU decrescente (mais recente primeiro).

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/received/list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "cnpj": "26638419000167",
          "doc_type": "resNFe",
          "chave": "",
          "emitente_cnpj": "",
          "start_create_time": "01/05/2026",
          "end_create_time": "31/05/2026",
          "page": 1,
          "page_size": 20
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "total": 3,
            "page": 1,
            "page_size": 20,
            "list": [
              {
                "id": "6a04a70d3201b5a62f3ac2f8",
                "nsu": 2318,
                "doc_type": "resNFe",
                "schema": "resNFe_v1.01.xsd",
                "chave": "35260563845920000120550020000085471156822656",
                "cnpj_destinatario": "26638419000167",
                "emitente_cnpj": "63845920000120",
                "emitente_nome": "MEGA ONLINE LTDA",
                "valor": 1.00,
                "dh_emi": "2026-05-13 14:05:35",
                "serie": 0,
                "number": 0,
                "tp_nf": 1,
                "c_sit_nfe": 3,
                "tp_evento": 0,
                "desc_evento": "",
                "n_seq_evento": 0,
                "dh_evento": null,
                "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
                "create": "2026-05-13 16:30:05"
              }
            ]
          }
        }

POST/api/invoice/received/get_xml

Obter XML do documento recebido

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ObjectId do documento — retornado em `/received/list`

Sobre o XML retornado:

resNFe — XML é apenas o resumo, NÃO contém produtos/impostos. Use para auditoria/triagem antes de manifestar Ciência
procNFe — XML completo e assinado, equivalente ao gerado pela emissão. Pronto para importar no ERP do cliente
procEvento — XML do evento completo com assinatura e protocolo

Erros Comuns

Mensagem	Causa
id inválido	Valor não é um ObjectId válido
documento recebido não encontrado	ObjectId existe mas não pertence ao usuário do token

POST/api/invoice/received/get_prod

Consultar produtos da NF-e recebida

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
chave	string	Sim	Chave de acesso de 44 dígitos da NF-e (modelo 55). O dígito verificador é conferido antes de consultar a SEFAZ
ciencia_nota	bool	Não	Padrão `false`. Com `true`, se a SEFAZ ainda não liberar o XML completo, o endpoint registra a Ciência da Operação (evento 210210) com o certificado da empresa e consulta de novo
ambiente	int	Não	`1` produção (padrão) ou `2` homologação

Campos da Resposta

Campo	Tipo	Descrição
chave	string	Chave de acesso consultada
total_itens	number	Quantidade de itens da nota
itens	array	Um objeto por item (`det`) da NF-e
itens[].nItem	number	Número do item dentro da nota
itens[].prod	object	Grupo `prod` do leiaute da NF-e, com os nomes originais das tags. Quantidades e valores vêm como número; códigos como `cProd`, `NCM` e `cEAN` vêm como texto, preservando zeros à esquerda. Tags que se repetem no leiaute (`NVE`, `DI`, `detExport`, `rastro`) vêm sempre como lista
itens[].infAdProd	string	Informação adicional do item, quando houver

Como a SEFAZ entrega o XML

A empresa destinatária vem do token; não envie CNPJ no corpo.
A consulta usa a distribuição de documentos (DistDFe) no Ambiente Nacional, com o certificado da própria empresa.
Sem manifestação, a SEFAZ devolve apenas o resumo, sem itens. Use ciencia_nota: true para liberar o XML completo.
A Ciência apenas declara conhecimento da nota: não confirma o recebimento da mercadoria nem impede o cancelamento pelo emitente.
Nota recém-autorizada pode levar horas até o Ambiente Nacional distribuí-la. Nesse intervalo a resposta é nota não localizada.
Nota emitida pela própria empresa não é distribuída a ela; consulte com o token da empresa destinatária.
A consulta não grava nada. Apenas a Ciência, quando acionada, registra um evento na SEFAZ.

Erros Comuns

Mensagem	Causa
Chave inserida inválida / 发票密钥无效	Chave sem 44 dígitos, com caractere não numérico ou com dígito verificador incorreto
Apenas NF-e modelo 55 pode ser consultada pela chave	A chave é de NFC-e (modelo 65), que a SEFAZ não distribui
empresa não encontrada para este token	O token não está vinculado a nenhuma empresa cadastrada
empresa não possui certificado configurado	A empresa não tem certificado A1 válido no cadastro
nenhum documento localizado para esta chave e este CNPJ...	O Ambiente Nacional ainda não distribuiu a nota, o ambiente é outro, ou a empresa não é a destinatária
esta nota foi emitida por este CNPJ e a SEFAZ não a distribui ao próprio emitente	Consulta de nota de saída com o token de quem a emitiu (SEFAZ 641)
SEFAZ devolveu apenas o resumo da nota (sem itens)...	Nota ainda sem Ciência da Operação; chame com `ciencia_nota=true`
consumo indevido: a SEFAZ bloqueou consultas repetidas	Limite da SEFAZ por CNPJ; aguarde antes de tentar de novo

Quando a flag ciencia_nota provoca o envio ou encontra uma Ciência já registrada, a resposta de erro traz data.ciencia com o resultado do evento. Nos demais erros a resposta tem apenas success e message.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/received/get_prod" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "chave": "35260912345678000195550010000012341000012345",
          "ciencia_nota": false
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "chave": "35260912345678000195550010000012341000012345",
            "total_itens": 1,
            "itens": [
              {
                "nItem": 1,
                "prod": {
                  "cProd": "PROD-A",
                  "cEAN": "SEM GTIN",
                  "xProd": "Produto exemplo",
                  "NCM": "84733011",
                  "CFOP": 5102,
                  "uCom": "UN",
                  "qCom": 1.0000,
                  "vUnCom": 1.0000000000,
                  "vProd": 1.00,
                  "cEANTrib": "SEM GTIN",
                  "uTrib": "UN",
                  "qTrib": 1.0000,
                  "vUnTrib": 1.0000000000,
                  "indTot": 1,
                  "xPed": "PED-77"
                }
              }
            ]
          }
        }

POST/api/invoice/received/get_sync_status

Consultar status da sincronização

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Tipo	Obrigatório	Descrição
cnpj	string	Sim	CNPJ da empresa destinatária — 14 dígitos, sem formatação

Campos da Resposta

Campo	Tipo	Descrição
cnpj	string	CNPJ consultado
uf	string	UF do destinatário usada na última sincronização (ausente se nunca sincronizou)
ult_nsu	long	Último NSU processado. `0` = nunca sincronizou
max_nsu	long	Maior NSU disponível no Fisco na última sincronização
pending	long	Documentos pendentes (`max_nsu - ult_nsu`). Se > 0, há novos documentos no Fisco
last_sync	string	Data/hora UTC da última sincronização bem-sucedida. `null` se nunca sincronizou

Uso típico: chame esse endpoint antes de /received/sync para decidir se precisa chamar o Fisco. Esse endpoint não consome o rate limit do Fisco — só lê o estado local do MongoDB.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/received/get_sync_status" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "cnpj": "26638419000167"
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "cnpj": "26638419000167",
            "uf": "SP",
            "ult_nsu": 2323,
            "max_nsu": 2323,
            "pending": 0,
            "last_sync": "2026-05-13 16:30:05"
          }
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "cnpj": "26638419000167",
            "ult_nsu": 0,
            "max_nsu": 0,
            "pending": 0,
            "last_sync": null
          }
        }