Received Documents & DistDFe

Note

Recipient Manifestation

Recipient Manifestation allows the NF-e recipient to formally position themselves regarding an invoice issued against their CNPJ. There are 4 event types defined by the tax authority, each with its own legal meaning.

Event Types

Code	Name	Meaning	Justification
210210	Operation Awareness	The recipient acknowledges the NF-e exists but has neither confirmed nor rejected it yet. Usually the first event, and a requirement to download the full XML via DistDFe.	Not required
210200	Operation Confirmation	The recipient confirms the operation took place and the goods/services were received. Final event, proves receipt.	Not required
210220	Operation Unawareness	The recipient declares they do NOT recognize the operation (suspected fraud, misuse of CNPJ, etc.).	Required (15-255 chars)
210240	Operation Not Performed	The recipient acknowledges the operation but declares it did NOT take place (return, refusal of delivery, etc.).	Required (15-255 chars)

Sequence rule: After sending Awareness (210210), you may send Confirmation (210200) OR Unawareness (210220) OR Not Performed (210240). Confirmation/Unawareness/Not Performed are final states — they cannot be overwritten.

Attention: The CNPJ sent in the cnpj field must be the recipient of the NF-e (the one manifesting) and must be registered in the system bound to the token in use. Otherwise tax authority returns the rejection "The event author differs from the NF-e recipient".

Return cStat Codes

cStat	Meaning
135	✅ Event successfully registered
573	✅ Event duplicity — already registered (treated as success)
236	❌ Invalid access key
491	❌ Manifestation already registered — cannot overwrite final state
596	❌ Recipient CNPJ differs from informed one
656	❌ Improper consumption (rate limit)

POST/api/invoice/manifest

Send recipient manifestation event

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
chave	string	Yes	NF-e access key — 44 digits
cnpj	string	Yes	Recipient CNPJ (the one manifesting) — 14 digits, unformatted. Must be registered in the system
tipo_evento	int	Yes	Event code: `210200`, `210210`, `210220` or `210240`
justificativa	string	Conditional	Required for `210220` and `210240`. Must be 15–255 characters. Ignored for `210200` and `210210`

Sequence (nSeqEvento): calculated automatically. For the same combination (cnpj + chave + tipo_evento) it increments on each call — so duplicates return cStat: 573 and are saved without error.

Response Fields

Field	Type	Description
id	string	Internal ObjectId of the manifestation record (used in `/get_xml`)
chave	string	Access key of the manifested NF-e
cnpj	string	Recipient CNPJ that manifested
tipo_evento	int	Event code sent (210200/210210/210220/210240)
desc_evento	string	Event textual description (tax authority original wording)
nProt	string	tax authority protocol number — event receipt
cStat	int	tax authority status code. `135` = registered, `573` = duplicity (also accepted)
xMotivo	string	tax authority descriptive return message
nSeqEvento	int	Event sequence assigned automatically
xml_url	string	Public URL of the procEvento XML (signed and protocoled) stored in OSS

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

List manifestations

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
cnpj	string	No	Filter by recipient CNPJ. If omitted, lists across all of the user's CNPJs
chave	string	No	Filter by a specific NF-e access key (44 digits)
start_create_time	string/long	No	Start date. Accepts: `"dd/MM/yyyy"`, `"yyyy-MM-dd"`, `"dd/MM/yyyy HH:mm:ss"` or Unix timestamp in seconds. Considers 00:00:00 UTC if date-only
end_create_time	string/long	No	End date. Same formats. If date-only, considers 23:59:59.999 UTC
page	int	No	Page number (default `1`)
page_size	int	No	Items per page (default `20`, max `100`)

Response Fields

Field	Type	Description
total	int	Total records matching the filters (regardless of pagination)
page	int	Current page returned
page_size	int	Page size returned
list[].id	string	Internal ObjectId of the record
list[].chave	string	Access key of the manifested NF-e
list[].cnpj	string	Recipient CNPJ that manifested
list[].tipo_evento	int	Event code (210200/210210/210220/210240)
list[].desc_evento	string	Event textual description
list[].justificativa	string	Sent justification (filled only for 210220/210240)
list[].nProt	string	tax authority protocol number for the event
list[].nSeqEvento	int	Event sequence
list[].cStat	int	tax authority status code
list[].xMotivo	string	tax authority descriptive return message
list[].xml_url	string	Public URL of the procEvento XML in OSS
list[].create	string	UTC creation timestamp (format `yyyy-MM-dd HH:mm:ss`)

Ordering: records are returned from newest to oldest (by create descending).

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Get manifestation XML

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
id	string	Yes	Manifestation ObjectId — returned by `/manifest` or `/manifest/list`

Common Errors

Message	Cause
id inválido	Value is not a valid ObjectId
manifestação não encontrada	ObjectId exists but does not belong to the token's user, or was deleted

Note

DistDFe Capture — Received NFes

Allows querying and downloading NFes and events destined to your CNPJ via the NFeDistribuicaoDFe service from the tax authority (National Environment). Capture is incremental by NSU (Unique Sequential Number) — each call only downloads what has not been captured yet.

Returned Document Types

doc_type	What it is	Content
resNFe	NFe summary	Basic metadata (key, value, issuer, status). Comes BEFORE the Awareness event is sent — does not contain products/taxes
procNFe	Full authorized NFe	Complete NF-e XML (with products, taxes, transport, etc.). Only available AFTER the recipient sends Awareness (210210) for the key
resEvento	Event summary	Event metadata (key, type, sequence, reason)
procEvento	Full event	Complete event XML (CC-e, cancellation, manifestations from other recipients on your invoices)

Recommended flow:

Call /received/sync — downloads all new documents
List with /received/list filtering by doc_type: "resNFe" to see invoices without Awareness
For each key of interest, call /invoice/manifest with tipo_evento: 210210
Call /received/sync again — now tax authority returns the procNFe (full XML) of the manifested keys
Use /received/get_xml to fetch the XML URL and process

tax authority rate limit: tax authority allows at most 1 DistDFe call per hour per CNPJ. Exceeding this returns cStat: 656 (Improper Consumption). In homologation the rule is more permissive.

DistDFe Return cStat Codes

cStat	Meaning
137	✅ No documents found (normal end of loop)
138	✅ Documents found — loop continues
656	❌ Improper consumption — wait 1h and retry
252	❌ Environment differs from informed (production vs homologation)
280	❌ Certificate expired or invalid

POST/api/invoice/received/sync

Sync received documents

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
cnpj	string	Yes	Recipient company CNPJ — 14 digits, unformatted. Must be registered in the system bound to the token
max_iterations	int	No	Maximum number of the tax authority calls per execution. Each call downloads up to 50 documents. Default `50` (≈2,500 docs), max `200`

How it works:

Reads the last ultNSU persisted for that (uid + cnpj)
Loops calling tax authority until cStat ≠ 138 or max_iterations is reached
Decompresses the returned XMLs (gzip)
Persists each document in w_invoice_received with XML uploaded to OSS
Updates ultNSU and maxNSU in w_invoice_received_sync
Deduplicates by (uid + cnpj + nsu) — repeated calls don't duplicate

Response Fields

Field	Type	Description
cnpj	string	Recipient CNPJ queried
uf	string	Recipient state used in the query
initial_nsu	long	Starting NSU — the last one processed before this run
ult_nsu	long	New last NSU after the sync
max_nsu	long	Largest NSU available in the national environment (AN) at the time of the query
pending	long	Documents still pending (`max_nsu - ult_nsu`). If > 0, call `/sync` again to download the rest
iterations	int	How many tax authority calls were made in this run
last_cstat	int	Last cStat returned by the tax authority. `137` is normal end, `656` is rate limit
last_motivo	string	tax authority descriptive return message for the last call
stats.resNFe	int	Number of NFe summaries downloaded in this run
stats.procNFe	int	Number of full NFes downloaded
stats.resEvento	int	Number of event summaries downloaded
stats.procEvento	int	Number of full events downloaded
stats.skipped	int	Documents skipped (duplicates or isolated parse error)

Initial volume: companies that have never synced may have hundreds to thousands of historical documents. The first run may take longer and be interrupted by max_iterations. Check pending in the response — if > 0, call again (respecting the rate limit).

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

List received documents

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
cnpj	string	No	Filter by recipient CNPJ (your CNPJ). If omitted, lists across all of the user's
doc_type	string	No	Filter by document type: `resNFe`, `procNFe`, `resEvento` or `procEvento`
chave	string	No	Filter by access key (44 digits)
emitente_cnpj	string	No	Filter by NF-e issuer CNPJ (supplier)
start_create_time	string/long	No	Start date. Accepts `"dd/MM/yyyy"`, ISO or Unix timestamp
end_create_time	string/long	No	End date. Same formats
page	int	No	Page number (default `1`)
page_size	int	No	Items per page (default `20`, max `100`)

Response Fields

Field	Type	Description
total	int	Total records matching the filters
page	int	Current page
page_size	int	Page size
list[].id	string	Internal ObjectId (use in `/received/get_xml`)
list[].nsu	long	NSU assigned by the tax authority to this document
list[].doc_type	string	Document type: `resNFe`, `procNFe`, `resEvento`, `procEvento`
list[].schema	string	Document schema (e.g. `resNFe_v1.01.xsd`)
list[].chave	string	NF-e access key (44 digits)
list[].cnpj_destinatario	string	Recipient CNPJ (your CNPJ)
list[].emitente_cnpj	string	NF-e issuer CNPJ (supplier)
list[].emitente_nome	string	Issuer company name
list[].valor	decimal	NF-e total value (`vNF`)
list[].dh_emi	string	NF-e issuance date/time
list[].serie	int	NF-e series (filled only for `procNFe`)
list[].number	long	NF-e number (filled only for `procNFe`)
list[].tp_nf	int	Operation type: `0`=Inbound, `1`=Outbound (from the issuer's perspective)
list[].c_sit_nfe	int	NF-e status (filled in `resNFe`): `1`=Authorized, `2`=Denied, `3`=Canceled
list[].tp_evento	int	Event code (filled in `resEvento`/`procEvento`). E.g. `110110`=CC-e, `110111`=Cancellation, `210210`=Awareness
list[].desc_evento	string	Event textual description
list[].n_seq_evento	int	Event sequence
list[].dh_evento	string	Event date/time (events only)
list[].xml_url	string	Public URL of the document XML in OSS
list[].create	string	UTC capture timestamp

Ordering: records are returned by NSU descending (most recent first).

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Get received document XML

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
id	string	Yes	Document ObjectId — returned by `/received/list`

About the returned XML:

resNFe — XML is the summary only, does NOT contain products/taxes. Use for auditing/triage before sending Awareness
procNFe — Full signed XML, equivalent to the one generated at issuance. Ready to import into the client's ERP
procEvento — Full event XML with signature and protocol

Common Errors

Message	Cause
id inválido	Value is not a valid ObjectId
documento recebido não encontrado	ObjectId exists but does not belong to the token's user

POST/api/invoice/received/get_prod

Get products from received NF-e

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
chave	string	Yes	44-digit NF-e access key (model 55). The check digit is validated before calling SEFAZ
ciencia_nota	bool	No	Defaults to `false`. With `true`, if SEFAZ has not released the full XML yet, the endpoint registers the Acknowledgement of Operation (event 210210) with the company certificate and queries again
ambiente	int	No	`1` production (default) or `2` staging

Response Fields

Field	Type	Description
chave	string	Access key that was queried
total_itens	number	Number of items in the invoice
itens	array	One object per invoice item (`det`)
itens[].nItem	number	Item number within the invoice
itens[].prod	object	The `prod` group of the NF-e layout, keeping the original tag names. Quantities and amounts come as numbers; codes such as `cProd`, `NCM` and `cEAN` come as text, preserving leading zeros. Tags that repeat in the layout (`NVE`, `DI`, `detExport`, `rastro`) always come as a list
itens[].infAdProd	string	Additional item information, when present

How SEFAZ delivers the XML

The receiving company comes from the token; do not send a CNPJ in the body.
The query uses document distribution (DistDFe) at the National Environment, with the company’s own certificate.
Without a manifestation, SEFAZ returns only the summary, with no items. Use ciencia_nota: true to release the full XML.
The Acknowledgement only states awareness of the invoice: it neither confirms receipt of the goods nor prevents the issuer from cancelling it.
A freshly authorized invoice may take hours until the National Environment distributes it. Until then the response is invoice not found.
An invoice issued by the company itself is not distributed to it; query with the receiving company’s token.
The query stores nothing. Only the Acknowledgement, when triggered, registers an event at SEFAZ.

Common Errors

Message	Cause
Chave inserida inválida / 发票密钥无效	Key without 44 digits, with a non-numeric character, or with a wrong check digit
Apenas NF-e modelo 55 pode ser consultada pela chave	The key belongs to an NFC-e (model 65), which SEFAZ does not distribute
empresa não encontrada para este token	The token is not linked to any registered company
empresa não possui certificado configurado	The company has no valid A1 certificate on file
nenhum documento localizado para esta chave e este CNPJ...	The National Environment has not distributed the invoice yet, the environment is different, or the company is not the recipient
esta nota foi emitida por este CNPJ e a SEFAZ não a distribui ao próprio emitente	Querying an outgoing invoice with the issuer’s own token (SEFAZ 641)
SEFAZ devolveu apenas o resumo da nota (sem itens)...	Invoice still without Acknowledgement; call with `ciencia_nota=true`
consumo indevido: a SEFAZ bloqueou consultas repetidas	SEFAZ per-CNPJ limit; wait before retrying

When the ciencia_nota flag triggers the event or finds one already registered, the error response carries data.ciencia with the event outcome. Every other error returns only success and message.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Get sync status

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Type	Required	Description
cnpj	string	Yes	Recipient company CNPJ — 14 digits, unformatted

Response Fields

Field	Type	Description
cnpj	string	CNPJ queried
uf	string	Recipient state used in the last sync (absent if never synced)
ult_nsu	long	Last NSU processed. `0` = never synced
max_nsu	long	Largest NSU available in the tax authority at the last sync
pending	long	Pending documents (`max_nsu - ult_nsu`). If > 0, there are new documents in the tax authority
last_sync	string	UTC date/time of the last successful sync. `null` if never synced

Typical use: call this endpoint before /received/sync to decide whether to call tax authority. This endpoint does not consume the tax authority rate limit — it only reads local MongoDB state.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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
          }
        }