Skip to content

Data Flow

Applies to: All subscriptions

Purpose

Trace a document through Complifly stage by stage so that, when one stops, you can say where it stopped and why without guessing. Most support escalations are a document in a state nobody expected; this page removes the surprise.

Audience

Solution architects, integration developers, support engineers, implementation consultants.

Prerequisites

Reference

The full path

  ERP / file
      |
      v
 [1] AUTHENTICATE ------ reject: bad credential, out-of-scope GSTIN
      |
      v
 [2] TRANSFORM --------- reject: mapping template missing or inactive
      |                          (mapped ingest only)
      v
 [3] VALIDATE ---------- quarantine: required field, format, or rule failure
      |
      v
 [4] DUPLICATE CHECK --- reject: document number already present
      |
      v
 [5] ROUTE ------------- decides IRN route or e-Way-Bill-only route
      |
      v
 [6] STORE ------------- document now exists, status PENDING or EWB_PENDING
      |
      +--> [6a] CORRECTION COCKPIT --> PROMOTE --> back to [3]
      |
      v
 [7] GENERATE ---------- via GSP to NIC.  Failure: numbered NIC error
      |                  Success: IRN, signed QR, acknowledgement stored
      v
 [8] E-WAY BILL -------- optional. Part-A, Part-B, validity
      |
      v
 [9] PRINT ------------- rendered from stored data, not re-fetched
      |
      v
 [10] WRITE-BACK ------- outbox -> retry -> ERP.  Off by default

Stage by stage

# Stage What it does Where it can stop Who resolves
1 Authenticate Verifies the caller and checks the document's supplier GSTIN is within the credential's scope Invalid or revoked credential; GSTIN outside scope Administrator
2 Transform Applies the mapping template, converting ERP field names, dates and codes into the NIC envelope Template missing, inactive, or a rule produces an unusable value Integration developer
3 Validate Checks required fields, formats and GST rules — before any government call Any failure quarantines the document User, in the Correction Cockpit
4 Duplicate check Confirms the document number is not already held Rejected as duplicate User or ERP owner
5 Route Decides IRN versus e-Way-Bill-only from the document type Does not stop; may route unexpectedly if the type is wrong Configuration
6 Store Persists the document with an initial status Does not stop —
7 Generate Calls the GSP, which calls NIC. Stores IRN, signed QR, acknowledgement Numbered NIC rejection; GSP unreachable; reporting window closed Depends on the code — see Error Codes
8 e-Way Bill Generates from the IRN or from a standalone document; Part-B, extension, cancellation NIC rejection; missing transport details User
9 Print Renders from stored data Rendering resource exhaustion under bulk load Administrator
10 Write-back Emits an outbound event, retries, dead-letters after exhaustion ERP endpoint unreachable, refusing or rejecting Integration developer

Three properties that explain most surprises

Validation runs before the government call, always. A document that fails locally never reaches NIC. This is why "the invoice vanished after upload" is nearly always quarantine rather than loss: the platform held it deliberately rather than spending a billed call on a payload it knew would be rejected.

Printing is mostly local, with one exception that matters. The IRN, signed QR and payload are captured at generation time and never change, and Branded Print renders from them locally — fast, free, and unaffected by a provider outage.

The official NIC-format copy is different: the government serves it only for two days after generation. Complifly caches it at generation so it survives, but a copy that was never cached becomes permanently unobtainable once that window closes. So a print failure is usually local — and occasionally it is the closed window. See Print Configuration.

Write-back is emitted, not pushed synchronously. Generation completes whether or not the ERP is reachable. The event lands in an outbox and is dispatched with retry and circuit breaking. A dead ERP endpoint therefore delays write-back without ever blocking compliance. The corollary matters for integration design: delivery is asynchronous and may be repeated, so the ERP consumer must be idempotent.

Where state lives

Stage Observable as
Rejected at ingest Rejection record with a reason code; not a document
Quarantined Visible in the Correction Cockpit with per-field messages
Stored, pre-generation Status PENDING, or EWB_PENDING on the e-Way-Bill-only route
Generated Status IRN_GENERATED with IRN, signed QR and acknowledgement
Failed at NIC Status IRN_FAILED with the numbered error retained
Cancelled Status IRN_CANCELLED. The document number remains consumed at NIC
Write-back in flight Outbox statuses: pending, retrying, delivered, paused, failed

Status names are also help-registry keys, so each resolves to an explanation inside the product as well as in Error Code Reference.

Validation

To prove the flow end to end in a new environment, push one document and observe it at every stage rather than only at the end:

Stage How to observe Expected
Authenticate Ingest response HTTP 200 with a document identifier. A 401 or 403 stops here
Transform Compare the stored mapped payload with what the ERP sent Every mapped field carries the intended value; dates in the NIC format
Validate Correction Cockpit Document absent from quarantine means validation passed
Duplicate Ingest response No duplicate rejection on a genuinely new number
Route Document status after ingest PENDING for an invoice; EWB_PENDING for a challan
Generate Document after generation Status IRN_GENERATED, with a 64-character IRN and a signed QR present
Print Open the printed document Signed QR renders and scans
Write-back Outbox and the ERP Event reaches delivered, and the ERP shows the IRN

Run this once per environment and once per ERP integration. A document that reached IRN_GENERATED proves stages 1 to 7 in one observation, but it proves nothing about write-back, which is a separate path with separate failure modes.

Troubleshooting

Symptom Stage Likely cause Action
Ingest returns 403 1 The document's supplier GSTIN is outside the credential's scope Check the credential's GSTIN scope, not the user's permissions
Fields arrive empty or wrong 2 Mapping rule targets the wrong path, or a date format token is wrong Inspect the stored mapped payload before blaming validation. See Ingest Failures
Document uploaded but not in the workbench 3 Quarantined Open the Correction Cockpit; the per-field messages name the fault
Duplicate rejection on a document never sent before 4 ERP numbering restarted, or a second system sends the same series Fix the ERP series before sending more. See NIC Error Codes
Challan produced no IRN 5 Correct behaviour — that type routes to e-Way Bill only Override only if the business genuinely requires it. See Document Type Routing
Generation fails with a numbered error 7 A NIC rule was broken Look the code up in NIC Error Codes; the fix depends on who owns it
Generation fails with no NIC code 7 GSP unreachable, credentials expired, or the operation is unsupported for this provider Run the provider connection test and check the capability state
Cancel or extend fails after a provider switch 7, 8 The action must return to the provider that issued the document This is handled by provenance. If it still fails, see GSP Abstraction
Print fails while generation succeeded 9 Rendering resources or print configuration, never the government See Print Configuration
ERP never receives the IRN 10 Write-back disabled, or the event is retrying or dead-lettered Check the flag first, then the outbox. See Write-back Failures
ERP received the same event twice 10 Delivery is at-least-once by design Make the consumer idempotent on the event identifier