Processing Details and Polling-Frequency Rules — NF-e, CT-e and NFS-e Inbound

Product	NFE.io Fiscal Document Capture (dfetech-distribution-api)
Document	3 of 3 — Written description of the processing, the capture frequency and compliance with government rules
Version	1.1 — 2026-09-24
Audience	Customers, architecture teams, IT, audit and tax teams
Related documents	1 of 3 — Architecture · 2 of 3 — Processing flows · Versão em português

Contents

1. Executive summary
2. Concepts
3. Government rules governing capture
4. NF-e Inbound
5. CT-e Inbound
6. NFS-e Inbound
7. Polling-frequency comparison
8. Expected time until the document reaches the customer
9. Customer responsibilities
10. Government references

1. Executive summary

Fiscal Document Capture queries the national fiscal-document distribution environments on behalf of each customer company, using the company's own A1 digital certificate. Capture is continuous and automatic, and follows four rules of conduct:

1. While documents are pending in the national environment, NFE.io queries in a chain, batch after batch, always starting from the last NSU returned by the environment itself, until the queue is empty.
2. When the national environment reports that there are no new documents, NFE.io waits at least 1 hour before querying that company again. This is the usage rule set by the Technical Notes to avoid rejection for improper consumption.
3. When the national environment signals a restriction or an outage, NFE.io suspends queries for a defined period and resumes on its own, with no action needed from the customer. For NF-e and CT-e, rejections block the company for 1 hour and service shutdowns pause queries for 5 or 20 minutes. For NFS-e, queries are suspended when the ADN signals a consumption limit (HTTP 429), when there are no new documents, when the ADN rejects the query before any document was captured, and when the certificate is unavailable.
4. Point queries (by NSU or by access key) are limited to 20 per hour per CNPJ for NF-e and CT-e. Only queries that return the document count. They are not part of routine capture and are used only in gap recovery and reprocessing.

The only manifestation NFE.io sends automatically is the NF-e Awareness of Operation (210210), when the company enables it. Conclusive NF-e manifestations and NFS-e taker manifestations are always the customer's decision.

Under normal conditions, a new document reaches the customer's system within about 1 hour after it becomes available in the national environment. During an initial load or an issuing peak, capture is faster, because queries are chained while documents are pending.

2. Concepts

Term	Meaning
National Environment (AN)	Environment run by the tax administration that centralizes the distribution of NF-e and CT-e to the parties involved. The NF-e web service is NFeDistribuicaoDFe; the CT-e web service is CTeDistribuicaoDFe.
ADN	National Data Environment of the National NFS-e System, which distributes National Standard NFS-e, DPS and events to taxpayers.
NSU	Unique Sequential Number. The national environment numbers each document or event made available, per interested CNPJ. It is the capture cursor.
ultNSU	Last NSU searched by the national environment in the response. The next query must start from it.
maxNSU	Highest NSU that exists in the national environment for the queried CNPJ. When ultNSU equals maxNSU, no documents are pending.
cStat	Status code returned by the NF-e and CT-e web services. The most relevant are 138 (document found), 137 (no document found) and 656 (improper consumption).
docZip	Each document in a distribution batch, GZip-compressed and Base64-encoded.
Summary (resNFe)	Summarized NF-e information generated by the National Environment for the recipient before the manifestation.
Recipient manifestation	Events through which the NF-e recipient states its position on the transaction: Awareness of Operation (210210), Confirmation of Operation (210200), Unknown Operation (210220) and Operation Not Performed (210240).
Cursor	The NSU from which NFE.io will make the next query for a company. It is saved with every batch.
Point query	A query for a single document, by NSU (consNSU) or by access key (consChNFe), outside the sequential distribution.

3. Government rules governing capture

3.1 NF-e — Technical Note 2014.002 and distribution schemas

Rule	Content
Web service	NFeDistribuicaoDFe, in the National Environment, authenticated with the interested party's ICP-Brasil digital certificate.
Query modes	distNSU (distribution from the last NSU received), consNSU (query of a specific NSU, for a missing NSU) and consChNFe (query by access key).
Batch size	At most 50 documents per response (loteDistDFeInt).
Continuity	Subsequent queries must use the ultNSU returned by the web service.
Availability window	With ultNSU set to zero or very old, the National Environment returns the documents received in the last 3 months. Queries by NSU and by access key cover documents received in the last 90 days.
Wait when there are no documents	When there are no more documents (cStat 137, or ultNSU equal to maxNSU), the interested party must wait 1 hour before querying again.
Improper consumption	Queries that break the usage rules receive cStat 656 and the CNPJ is blocked for 1 hour.
Who receives what	The recipient receives the summary (resNFe) and, after an Awareness, Confirmation or Operation Not Performed manifestation, the full NF-e. The carrier and third parties authorized in the autXML group receive the full NF-e. The issuer receives the distributable events, but not the NF-e itself.

3.2 NF-e — Recipient manifestation (Technical Note 2020.001 and Ajuste SINIEF 07/05)

• Events are registered in the National Environment's NFeRecepcaoEvento4 web service.
• Awareness of Operation (210210) is not a conclusive manifestation. It releases the full XML, but the NF-e is still subject to a conclusive manifestation (Confirmation, Unknown Operation or Operation Not Performed) within the deadline set by law.
• Operation Not Performed (210240) requires a justification of 15 to 255 characters.
• Recipient events introduced by the Consumption Tax Reform follow Technical Note 2025.002 and are registered in the event environment designated for them.

3.3 CT-e — Technical Note 2015.002 and distribution schemas

Rule	Content
Web service	CTeDistribuicaoDFe, in the National Environment, authenticated with the interested party's digital certificate and with the author's state (cUFAutor) mandatory.
Query modes	Only distNSU and consNSU. There is no query by access key in the CT-e distribution web service.
Batch size	At most 50 documents per response.
Availability window	With ultNSU set to zero or very old, the documents from the last 3 months are returned.
Improper consumption	The web service keeps controls against successive attempts to fetch records already made available and rejects such attempts with cStat 656.
Who receives	Issuer, sender, recipient, dispatcher, receiver, taker and authorized third parties (autXML). The full CT-e is distributed without any manifestation.

3.4 NFS-e — National NFS-e System (Taxpayer Manual: ADN APIs)

Rule	Content
API	ADN GET /DFe/{NSU}, which returns the service fiscal documents from the NSU given, and GET /NFSe/{ChaveAcesso}/Eventos for the events of an NFS-e.
Authentication	Mutual TLS with the taxpayer's ICP-Brasil certificate (e-CNPJ).
Who receives	The taxpayer queries the documents in which it appears as issuer (service provider), taker or intermediary.
Continuity	The taxpayer keeps track of the last NSU received and resumes from it.

For NFS-e, NFE.io applies by default the same consumption discipline used for NF-e and CT-e (a 1-hour wait when there are no documents) and fully honors the ADN's consumption-limit signal (HTTP 429 with the indicated wait time).

---

4. NF-e Inbound

4.1 Enablement and prerequisites

1. The company must be registered with NFE.io with a valid A1 digital certificate (ICP-Brasil e-CNPJ). Certificates with the key held in an HSM are not supported for capture.
2. Capture is enabled per company, through the API or the console, by choosing the SEFAZ environment (production or homologation) and, optionally, the automatic Awareness of Operation, with the waiting time in minutes before it is sent (AutomaticManifesting.MinutesToWaitAwarenessOperation, minimum 5).
3. On the first enablement, capture starts from NSU zero. Under the National Environment rule, the first sequence of queries returns the documents received in the last 3 months. After that, capture proceeds with new documents only.

4.2 Capture frequency

Parameter	Value	Purpose
Scheduler cycle	every 3 minutes	Evaluates all active companies and decides which can be queried now.
Eligibility	company with a pending continuation, or last query more than 61 minutes ago	Ensures that a company with no new documents is only evaluated again after 1 hour.
Empty-queue lock	new query blocked for 62 minutes after the cursor reaches maxNSU	Implements the 1-hour wait rule of TN 2014.002, with a safety margin.
Chaining	immediate query while ultNSU is lower than maxNSU	Drains the National Environment queue as fast as possible, as the TN provides.
Timeout per call	5 minutes	Avoids stuck queries when the web service is slow.

In practice, a company whose queue is up to date is queried once per hour (an effective interval of 62 to 65 minutes). A company with pending documents is queried in sequence, batch after batch, until it reaches maxNSU.

4.3 Capture, step by step

1. Selection. Every 3 minutes, the scheduler lists the companies with capture enabled and sends a capture message for each eligible company. The message identifier combines the company and the NSU, which prevents two identical captures from running in parallel.
2. Checks before querying. Capture does not call the web service if: (a) a global pause is active because SEFAZ is shut down; (b) the company is blocked by a recent rejection, including improper consumption (cStat 656); (c) the cursor is already at maxNSU and the last query was less than 62 minutes ago.
3. Certificate. The company's A1 certificate is fetched from the NFE.io certificate service and loaded in memory. An expired certificate stops the query.
4. Query. NFE.io calls NFeDistribuicaoDFe in distNSU mode, with ultNSU equal to the company cursor, the company's CNPJ and the author's state. Responses with documents and rejections (except 656) are archived.
5. Response with documents (cStat 138). The batch is stored, one processing item is created for each NSU between the batch's first NSU and ultNSU, and one message is sent per NSU. The cursor is updated with the returned ultNSU and maxNSU. If ultNSU is still lower than maxNSU, the next query is triggered immediately.
6. Response without documents (cStat 137). The query time is recorded and the company enters the 1-hour wait.
7. SEFAZ shutdown. For cStat 108 (service temporarily shut down), queries for all companies are paused for 5 minutes. For cStat 109 (service shut down with no forecast), for 20 minutes.
8. Improper consumption (cStat 656). The rejection is recorded and the company goes 1 hour without new distribution queries. Point queries for the same CNPJ are also suspended for the same hour (section 4.6). The cursor is moved to the ultNSU returned by the National Environment, forward only: it never goes back and the known maxNSU never decreases. The 656 does not affect the automatic Awareness, which uses a different web service. In normal operation, the 656 is avoided by the 1-hour wait when the queue is up to date, described in item 6 and in section 4.2.
9. Other rejections. Other rejections are recorded and the company goes 1 hour without new queries.
10. Communication failure. The query is retried automatically. If the same query keeps failing and reaches the attempt limit, it is stopped and routed to the operations team, so that it does not consume the web service indefinitely.

4.4 Processing each document

1. The NSU item is read, the matching docZip is found in the archived batch, Base64-decoded and GZip-decompressed.
2. The type is identified by the schema attribute:

Schema	Type	Notification
procNFe	Full authorized NF-e	product_invoice_inbound — issued_successfully (received) or outbound_successfully (issued by the company itself)
resNFe	NF-e summary	product_invoice_inbound_summary
procEventoNFe	Full event (cancellation, correction letter, manifestations, etc.)	product_invoice_inbound — input_event_raised_successfully for recipient manifestations; event_raised_successfully for the others
resEvento	Event summary	product_invoice_inbound_summary — event_raised_successfully

3. Metadata is extracted: access key, state, number, series, issue date and time with time zone, issuer, recipient, carrier, total amount, operation type and environment.
4. The direction is determined: the document is "issued" only when the company is the issuer and holds no other role (recipient or carrier); otherwise it is "received".
5. The XML is stored in object storage and the metadata in the database. Events are linked to the NF-e with the same key.
6. The webhook is sent and usage is recorded.
7. If processing fails, the item goes back to the queue and is retried automatically. Items idle for more than 2 hours are resent by the scheduler.

4.5 Recipient manifestation

• Automatic Awareness (optional). When enabled in the company settings, each summary (resNFe) received schedules a 210210 — Awareness of Operation event for after the configured waiting time (MinutesToWaitAwarenessOperation). When it is due, NFE.io checks the situation again. The Awareness is not sent if the company has turned the automatic Awareness off, or if the customer already has an accepted conclusive manifestation for the key. A conclusive manifestation that is still pending does not cancel the Awareness, because it may be rejected. The event is signed with the company's A1 certificate and sent to the National Environment's NFeRecepcaoEvento4. Duplicate submissions for the same key are prevented. While the Awareness is waiting, the summary is not reprocessed or notified again.
• Only automatic manifestation. The Awareness of Operation is the only manifestation NFE.io sends without a customer request. Confirmation (210200), Unknown Operation (210220) and Operation Not Performed (210240) are always the customer's decision and are sent only when the customer registers them.
• Manifestation by the customer. Through the API or the console, the customer registers Confirmation (210200), Awareness (210210), Unknown Operation (210220) or Operation Not Performed (210240, with justification). The API also accepts the Tax Reform recipient events (TN 2025.002), which are sent to the corresponding event environment. Submission is asynchronous: the API replies that the request is pending and the result is available for query.
• Result. cStat 135 or 136 means the event was registered. cStat 573 (duplicate event) is treated as success. Other rejections close the request as rejected. Communication failures are retried automatically.
• Full XML. NFE.io does not need to query the access key after the Awareness. Once the manifestation is registered, the National Environment makes the full NF-e (procNFe) available with a new NSU, which arrives through the normal capture flow and produces the issued_successfully webhook.

4.6 Point queries (consNSU and consChNFe)

The consNSU and consChNFe modes are not used in routine capture. They are used only in two exceptional situations:

1. Gap recovery (consNSU), described in section 4.7.
2. Reprocessing requested by the customer for a specific NSU or access key. In this case, NFE.io first looks for the document in its own database and only queries the National Environment if it does not exist locally.

Recovery queries are spaced out with an exponential wait (from 1 minute to 30 minutes, with random jitter) and limited to 8 attempts per NSU.

Consumption limit. Point queries are limited to 20 per hour per CNPJ, in a sliding window:

• Only queries that return the document count. A query with no document, a rejected query or a failed query returns its slot.
• Resending a document that already exists in the database does not query SEFAZ and does not use the quota.
• With no slot available, a query from the internal queue is deferred until the next slot, with random spacing of up to 30 minutes so that retries are not concentrated. The deferral does not count as an attempt.
• With no slot available, a request made through the reprocessing API receives HTTP 429, with the Retry-After header.
• A cStat 656 on a point query suspends the CNPJ's point queries for 1 hour and also records the company block for distribution.

4.7 NSU gap recovery

Every day at 11 p.m. (Brasília time), a routine run by a single instance checks, for each active company, the sequence of NSUs captured in the last 3 days. Every NSU missing from the range becomes a recovery item. Every 5 minutes, the items are dispatched for an individual consNSU query. When the document is recovered, it goes through normal processing and produces the webhook. Recovery honors the point-query limit in section 4.6: large gaps are recovered at up to 20 documents per hour per CNPJ.

4.8 PDF (DANFE)

The DANFE is generated on demand, from the stored XML, on the first PDF request. The generated file is stored and reused for later requests.

4.9 How NF-e Inbound complies with government rules

Rule (TN 2014.002)	NFE.io implementation
Always use the returned ultNSU	The company cursor is saved with the ultNSU of each response, and every distNSU query starts from it.
Wait 1 hour when there are no documents	62-minute lock after the cursor reaches maxNSU, plus the 61-minute eligibility in the scheduler.
At most 50 documents per batch	The batch is defined by the National Environment; NFE.io processes every NSU in the returned range.
3-month window	The first enablement starts from NSU zero and receives the history made available by the National Environment. Daily gap recovery works on the last 3 days, well within the window.
Exceptional use of consNSU and consChNFe	Used only for gap recovery and reprocessing, with exponential wait, an attempt limit and a limit of 20 queries that return a document per hour per CNPJ.
Avoid improper consumption during errors	Global pause of 5 minutes (cStat 108) or 20 minutes (cStat 109) during SEFAZ shutdowns and a 1-hour company block after a rejection, including 656, which also suspends the CNPJ's point queries. In normal operation, cStat 656 is avoided by the 1-hour wait when the queue is up to date.
A single query at a time per company	Message with a deterministic identifier and deduplication, plus company state control.
Manifestation through the event web service	Signed submission to NFeRecepcaoEvento4, with duplicate protection. The automatic Awareness honors the waiting time set by the company and is the only manifestation sent automatically.

---

5. CT-e Inbound

5.1 Enablement and prerequisites

1. The company must be registered with NFE.io with a valid A1 digital certificate. Certificates with the key held in an HSM are not supported.
2. Capture is enabled per company by choosing the SEFAZ environment (production or homologation). The company can configure:
   • Event type filter: events outside the list are stored but do not produce a webhook.
   • Interested-party filter: the webhook is sent only when the company holds one of the chosen roles in the CT-e (taker, sender, dispatcher, receiver or recipient). The document remains available in the API even when the webhook is suppressed.
3. Capture starts from NSU zero and, under the National Environment rule, the first sequence of queries returns the documents from the last 3 months.

5.2 Capture frequency

Parameter	Value	Purpose
Scheduler cycle	every 60 seconds	Evaluates all active companies.
Eligibility	company with a pending continuation, or last query more than 60 minutes ago	A company with no new documents is only queried again after 1 hour.
Empty-queue lock	new query blocked for 1 hour after a response with no documents	Applies to CT-e the same wait rule used for NF-e.
Chaining	immediate query while ultNSU is lower than maxNSU	Drains the National Environment queue.
Timeout per call	5 minutes	Avoids stuck queries.

5.3 Capture, step by step

1. Selection. Every 60 seconds, the scheduler sends a capture message for each eligible company. Companies with a capture in progress do not receive a new message.
2. Checks before querying. Capture does not call the web service if a global SEFAZ pause is active, if the company is blocked by a recent rejection, or if the last response indicated the end of the queue less than 1 hour ago.
3. Certificate and query. The A1 certificate is fetched into memory and NFE.io calls CTeDistribuicaoDFe in distNSU mode, with ultNSU equal to the cursor, the CNPJ and the author's state. The request and response are archived.
4. Response with documents (cStat 138). All NSUs in the batch are stored, with controlled parallelism. The cursor only advances after the batch has been persisted. If any NSU fails to be stored, it becomes an individual recovery item. If ultNSU is still lower than maxNSU, the next query is triggered immediately.
5. Response without documents (cStat 137). The cursor advances and the company enters the 1-hour wait.
6. SEFAZ shutdown. cStat 108 pauses all queries for 5 minutes; cStat 109, for 20 minutes.
7. Other rejections, including 656. The company goes 1 hour without new distribution queries and the error is recorded.
8. NSU beyond the maximum (cStat 589). This situation raises a critical alert for the operations team.

5.4 Processing each document

1. The NSU's docZip is found in the archived batch, decoded and decompressed.
2. The type is identified by schema:
   • procCTe: full CT-e. Extracted fields: key, state, issue date with time zone, CT-e type, transport mode, total service amount, issuer, sender, dispatcher, receiver, recipient, taker and keys of the NF-e being transported.
   • procEventoCTe: CT-e event. Extracted fields: type, sequence, registration date and description.
3. The direction is determined: the CT-e is "issued" only when the company is the issuer and holds no other role; otherwise it is "received".
4. Events whose type is not in the configured list are stored as ignored and do not produce a webhook.
5. The XML is stored in object storage and the metadata in the database.
6. If an interested-party filter exists, it is applied. Events follow the decision made for the CT-e they belong to.
7. The transportation_invoice_inbound webhook is sent (issued_successfully, outbound_successfully or event_raised_successfully) and usage is recorded.
8. Failed items are retried automatically. Items idle for more than 2 hours are resent by the scheduler.

5.5 Gap recovery and reprocessing

• Daily routine at 11 p.m. (Brasília time): checks the NSU sequence of the last 3 days and scans up to the company's current cursor. Each missing NSU becomes a recovery item and is queried with consNSU every 5 minutes, with an exponential wait (1 minute to 30 minutes, with random jitter) and up to 8 attempts. A 137 response for a specific NSU closes the item, because it means the NSU does not exist in the National Environment.
• Health alerts: the routine alerts operations when a company with pending documents goes many hours without capture, or when the cursor gets ahead of the National Environment.
• Reprocessing through the API: the customer can request reprocessing of an NSU, of an already archived batch (with no new SEFAZ query), or the resending of webhooks by key or by date.
• No query by key: since the CT-e distribution web service offers no query by access key, all recovery is done by NSU.
• Point-query limit: consNSU queries follow the same limit as NF-e (section 4.6), 20 that return a document per hour per CNPJ. Only queries that return the document count, and queries with no slot available are deferred without consuming an attempt. A cStat 656 on a consNSU query suspends the CNPJ's point queries for 1 hour.

5.6 PDF (DACTE)

The DACTE is generated on demand, on each request, from the stored XML.

5.7 How CT-e Inbound complies with government rules

Rule (TN 2015.002)	NFE.io implementation
Continuity through ultNSU	Cursor saved with the ultNSU of each response, only after the batch has been persisted.
Improper-consumption control (656)	1-hour wait after a response with no documents; 1-hour company block after 656 or any other rejection.
At most 50 documents per batch	Batch defined by the National Environment; every NSU in the range is processed.
Only distNSU and consNSU	Capture uses distNSU; consNSU only for gap recovery and item reprocessing, with a limit of 20 queries that return a document per hour per CNPJ.
3-month window	First enablement from NSU zero; daily recovery over the last 3 days.
Service shutdown	Global pause of 5 minutes (cStat 108) or 20 minutes (cStat 109), with automatic resumption.

---

6. NFS-e Inbound

6.1 Enablement and prerequisites

1. The company must be registered with NFE.io with a valid A1 digital certificate. The ADN requires mutual TLS with the taxpayer's certificate, and Fiscal Document Capture uses the A1 certificate (file) for it; certificates with the key held in an HSM are not yet supported. Enablement is refused if the certificate is missing or expired.
2. Capture is enabled per company by choosing the environment (production or restricted production), the webhook URL and, optionally:
   • Capture of NFS-e issued by the company itself: off by default. When off, NFS-e in which the company is only the service provider are neither listed nor notified.
   • Cutoff date: documents earlier than this date are stored, but they do not appear in the listing and produce no webhook. Release of this history can be contracted later with NFE.io.

6.2 Capture frequency

Parameter	Value	Purpose
Scheduler cycle	every 30 seconds	Selects active companies that are not in a wait period.
Batches per run	up to 50 consecutive queries per company	Drains the ADN queue quickly; anything left continues in the next cycle.
Wait with no documents	1 hour after NENHUM_DOCUMENTO_LOCALIZADO	Same consumption discipline applied to NF-e and CT-e.
ADN consumption limit	time given in the Retry-After header of the HTTP 429, or 1 hour	Fully honors the ADN signal.
ADN rejection (REJEICAO)	10-minute wait, only when the run captured no document	Avoids repeating the same rejected query every 30 seconds. After batches were captured, capture resumes in the next cycle.
Certificate unavailable	1-hour wait, with the company kept active	Resumes on its own when the certificate is fixed, without losing documents.
Concurrency	one capture per company at a time, through a distributed lock	Prevents simultaneous queries for the same CNPJ.
Timeout per call	60 seconds	Avoids stuck queries.

6.3 Capture, step by step

1. Selection. Every 30 seconds, the scheduler selects the active companies whose last run is older than the cycle and that are not in a wait period, and sends a capture message for each.
2. Lock. Capture takes the company lock. If another capture for the same company is running, the message is discarded.
3. Certificate. The A1 certificate is fetched into memory. If it is missing, expired or in an HSM, the company enters a 1-hour wait and remains active.
4. Query. NFE.io calls the ADN GET /DFe/{NSU}, in batch distribution mode, from the company cursor. Each request uses its own TLS connection with the company's certificate.
5. Documents found. One processing message is sent for each document in the batch and the cursor is saved with the highest NSU received. The query repeats, up to 50 times in the same run, while there are documents.
6. No document found. The cursor is saved and the company enters a 1-hour wait.
7. HTTP 429. The company waits for the time indicated by the ADN (or 1 hour if none is given).
8. Rejection. The error codes returned by the ADN are recorded. If the run captured no document, the company waits 10 minutes. If batches were already captured, the query is retried in the next cycle.
9. Transient failures (5xx errors, timeout). Up to 3 retries, waiting 1, 2 and 4 seconds, within the call timeout. Per-certificate (10 failures) and global (50 failures) circuit breakers stop calls for 60 seconds to protect the ADN during instability. If the failure persists, capture is rescheduled with an exponential wait from 1 minute up to 1 hour.
10. Certificate rejected by the ADN. Each rejection counts as a consecutive failure. After 10 consecutive failures, the company's capture is disabled and the NFE.io team is notified. Capture is reactivated once the cause has been fixed.

6.4 Processing each document

1. Idempotency. If the NSU has already been processed for the company, the message is ignored.
2. Decoding. The content is Base64-decoded, GZip-decompressed and read as UTF-8.
3. Classification by root element: authorized NFS-e, DPS, event (cancellation, cancellation by replacement, confirmations and rejections by provider, taker and intermediary, ex officio acts), event registration request or CNC. Documents of unknown type are stored with their XML and are also notified.
4. Storage. The XML is stored compressed in object storage.
5. PDF. For authorized NFS-e, the DANFSe is generated. If the PDF service is unavailable, the PDF stays pending and is generated at download time.
6. Metadata. Provider, taker, intermediary, service codes, amounts and taxes, including the Tax Reform IBS/CBS group when present. Events are linked to the corresponding NFS-e; the replacing NFS-e key is recorded on replacement events.
7. Direction. The NFS-e is "issued" only when the company is the provider and is neither the taker nor the intermediary.
8. Delivery rules. No webhook is sent for documents earlier than the cutoff date (while the history has not been released), nor for NFS-e issued by the company itself when that capture is off.
9. Webhook and usage. The service_invoice_inbound webhook is sent with the action issued_successfully (NFS-e received), outbound_successfully (NFS-e issued by the company itself) or event_raised_successfully (events). The body also carries the eventName field (inbound.serviceInvoice.received, inbound.serviceInvoice.issued or inbound.serviceInvoice.event.received). Usage is recorded. If delivery fails, it is retried with an exponential wait from 1 minute up to 1 hour.

6.5 Taker manifestation

• Through the API, the customer registers Taker Confirmation (203202) or Taker Rejection (203206), the latter with a reason.
• NFE.io does not send NFS-e manifestations automatically. Both are conclusive taker manifestations and are sent only when the customer registers them. The national NFS-e system has no event equivalent to the NF-e Awareness of Operation.
• Submission is asynchronous. NFE.io checks the certificate and whether the certificate's CNPJ is the taker's, signs the event registration request and sends it to Sefin Nacional.
• A registered manifestation produces the event_raised_successfully webhook. A rejection produces no webhook and is available for query in the API. NFS-e issued by the company itself cannot be manifested.

6.6 On-demand capture by access key

The customer can request, through the API, the immediate capture of an NFS-e by its 50-digit access key. NFE.io validates the key, queries the NFS-e directly from Sefin Nacional, stores the XML, generates the PDF and returns the document in the response itself. If the document already exists in the database, it is returned without a new query. On-demand capture does not produce a webhook. When the same document later arrives through normal distribution, it is recognized, is not duplicated, and the webhook is sent at that point.

6.7 Gap recovery

Every day at 11 p.m. (Brasília time), the routine checks the sequence of NSUs captured in the last 3 days. If it finds a gap, it restarts the company's capture from the NSU before the first gap. Documents that already exist are recognized through idempotency, and only the missing ones are stored and notified.

6.8 How NFS-e Inbound complies with government rules

Rule (National NFS-e System)	NFE.io implementation
Distribution by NSU (GET /DFe/{NSU})	Per-company cursor, saved with every batch, always with the highest NSU received.
Mutual TLS with the taxpayer's ICP-Brasil certificate	The company's own A1 certificate on every request, TLS 1.2 or 1.3, one isolated connection per request.
Only documents in which the company is a party	The ADN returns only the documents in which the company is the provider, taker or intermediary; NFE.io classifies the direction of each one.
Consumption limit signaled by the ADN	HTTP 429 honored with the Retry-After time.
Moderate use of the service	1-hour wait when there are no documents, 10-minute wait after a rejection with no documents captured, one capture per company at a time, circuit breakers and short, limited retries.

---

7. Polling-frequency comparison

Item	NF-e	CT-e	NFS-e
Government service	NFeDistribuicaoDFe (AN)	CTeDistribuicaoDFe (AN)	ADN — GET /DFe/{NSU}
Scheduler cycle	3 min	60 s	30 s
Query when the queue is up to date	once per hour (62 to 65 min)	once per hour	once per hour
Query when documents are pending	chained until ultNSU = maxNSU	chained until ultNSU = maxNSU	up to 50 batches per run, every 30 s
Documents per batch	up to 50 (AN rule)	up to 50 (AN rule)	defined by the ADN
After a rejection	company blocked for 1 h, including 656; 656 also suspends point queries	company blocked for 1 h, including 656	10-min wait if nothing was captured in the run; HTTP 429 per Retry-After
Service shutdown	global pause of 5 min (108) or 20 min (109)	global pause of 5 min (108) or 20 min (109)	retry, 60-s circuit breaker and exponential rescheduling
Query by key	point reprocessing only	does not exist in the web service	on-demand capture through the API
Point queries	up to 20 that return a document per hour per CNPJ (consNSU and consChNFe)	up to 20 that return a document per hour per CNPJ (consNSU)	not applicable
Gap recovery	daily at 11 p.m., 3-day window	daily at 11 p.m., 3-day window	daily at 11 p.m., 3-day window
Manifestation	210200, 210210, 210220, 210240 and Tax Reform events, at the customer's request; the optional automatic Awareness, after the configured waiting time, is the only automatic manifestation	not applicable	203202 and 203206, only at the customer's request

8. Expected time until the document reaches the customer

The total time has two parts:

1. Publication in the national environment. The interval between the document's authorization and its availability in the National Environment or the ADN depends on the government and is not controlled by NFE.io.
2. Capture by NFE.io. When the company's queue is up to date, NFE.io queries the national environment once per hour, as the usage rules require. A document published right after a query is therefore captured within about 1 hour (for NF-e, up to about 65 minutes). Processing, storage and webhook delivery take a few seconds under normal conditions.

On enablement and during issuing peaks, capture is faster, because queries are chained while documents are pending. On high-volume dates (such as month-end) or during government outages, the time may be longer.

Urgent documents:

• NFS-e: use on-demand capture by access key (section 6.6).
• NF-e: the full XML depends on the recipient manifestation. With automatic Awareness enabled, the event is sent after the waiting time set by the company, and the full XML arrives in the capture that follows the event registration. A shorter waiting time brings the full XML sooner.

9. Customer responsibilities

Responsibility	Detail
Valid digital certificate	Keep the company's A1 certificate up to date at NFE.io. An expired certificate stops capture (NF-e and CT-e) or puts it on hold (NFS-e).
Conclusive NF-e manifestation	Awareness of Operation is not conclusive. Registering Confirmation, Unknown Operation or Operation Not Performed within the legal deadline is the recipient's decision and responsibility. NFE.io never sends a conclusive manifestation automatically.
NFS-e taker manifestation	Taker Confirmation (203202) and Taker Rejection (203206) are the customer's decision and are sent only when the customer registers them through the API.
Idempotent webhook	Handle repeated notifications using the access key, the event identifier or the NSU, and reply with HTTP 2xx.
Webhook signature validation	Validate the signature of each notification, as described in the NFE.io webhook documentation.
Downloads	Do not store the signed download URLs; request a new one when needed.

10. Government references

• National NF-e Portal — https://www.nfe.fazenda.gov.br/portal
  • Technical Note 2014.002 — DF-e Distribution Web Service for NF-e Stakeholders (usage rules, improper consumption and limits).
  • Schemas distDFeInt_v1.01.xsd and retDistDFeInt_v1.01.xsd (query modes, batches of up to 50 documents, 3-month window).
  • Technical Note 2020.001 — Recipient Manifestation.
  • Technical Note 2025.002 — Consumption Tax Reform events.
• National CT-e Portal — https://www.cte.fazenda.gov.br/portal
  • Technical Note 2015.002 — DF-e Distribution Web Service for CT-e Stakeholders.
  • Schemas distDFeInt_v1.00.xsd and retDistDFeInt_v1.00.xsd.
• National NFS-e System — https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual
  • Taxpayer Manual — Guide to the ADN APIs.
• CONFAZ — Ajuste SINIEF 07/05, which establishes the NF-e: https://www.confaz.fazenda.gov.br/legislacao/ajustes/2005/AJ007_05