Skip to content

Document Type Routing

Applies to: e-Invoice · e-Way Bill · Which modules do I have?

Purpose

Explain how Complifly decides what happens to each document type, how to change that decision when the default does not match the business, and what an override commits you to.

Audience

Implementation consultants, system administrators, and the customer's tax lead — who owns the decision, even though an administrator makes the change.

Prerequisites

  • What Complifly Does
  • The customer's list of document types actually in use
  • Administrator access

Reference

The default routing

Routing is decided from the document type after mapping. That distinction matters for an API integration: the ERP's own code is translated by the mapping template first, and routing reads the translated value.

Type Meaning Route IRN issued Initial status
INV Tax Invoice IRN Yes PENDING
CRN Credit Note IRN Yes PENDING
DBN Debit Note IRN Yes PENDING
CHL Delivery Challan e-Way Bill only No EWB_PENDING
BIL Bill of Supply e-Way Bill only No EWB_PENDING
BOE Bill of Entry e-Way Bill only No EWB_PENDING

IRN route. The document is stored awaiting IRN generation. Once generated, an e-Way Bill can be raised from the IRN.

e-Way-Bill-only route. No IRN is issued — the document type does not attract one. An e-Way Bill is generated from the e-Way Bill workbench.

Overrides

Routing is configurable per company, with a global default as the fallback. The most common legitimate override is an organisation that wants delivery challans to also produce an IRN for internal control, beyond what statute requires.

Scope Wins over
Company-specific rule The global default
Global default The built-in behaviour

There is no admin console screen for this

Routing is configured through the API only. Unlike provider assignment, API keys and feature flags, document type routing has no screen in the admin console. If you are looking for it and cannot find it, that is why.

Note that the platform's own error message for an unrouted document type says "Configure it in Admin > Doc Type Routing" — pointing at a screen that does not exist. Treat that message as meaning "no rule exists for this type", and use the API below.

Base path /api/admin/doc-type-routing, authenticated with a user token carrying an administrative role. The company is taken from the token, not from the request.

See the current rules — global defaults plus any company overrides:

GET /api/admin/doc-type-routing

Each row reports its scope as global or company, and a global row that a company rule supersedes is flagged overridden_by_company.

Check how one type resolves today, before changing anything:

GET /api/admin/doc-type-routing/resolve/CHL

Add a company override:

POST /api/admin/doc-type-routing
Content-Type: application/json

{ "nicDocType": "CHL", "route": "IRN", "description": "Challans require IRN for internal control" }

route must be exactly IRN or EWB_ONLY; anything else is rejected.

Remove a company override, which restores the global default:

DELETE /api/admin/doc-type-routing/{id}

Two behaviours worth knowing before you plan a change:

Behaviour Consequence
There is no update operation A second POST for a document type that already has a company rule returns 409. To change a route you must DELETE the existing rule and POST the new one
Global defaults cannot be deleted Attempting it returns 404. You override a global default with a company rule; you do not remove it

Both create and delete are written to the audit trail, so routing changes are traceable even without a screen.

What an override commits you to

An override is a business decision with consequences that are easy to miss at the point of making it:

A document type routed to IRN must carry everything an IRN needs. Fields that were optional on the e-Way-Bill-only route become required. Overriding routing without checking the document's field completeness produces a wave of validation failures at the moment the change takes effect.

An IRN consumes a document number permanently. Once a challan series produces IRNs, those numbers can never be reused, and the challan series inherits the same uniqueness discipline as an invoice series.

Statutory intent should be confirmed by the tax lead. Producing an IRN where statute does not require one is not usually harmful, but it is a tax position and belongs to the customer's tax lead, not to an implementation team.

Changing a route, step by step

There is no update operation, so a change is always a delete followed by a create. Do the first four steps before touching anything.

1. Get the tax lead's endorsement, in writing

Routing decides whether a document type produces an IRN. That is a tax position and belongs to the customer's tax lead, not to an implementation team.

Check: you have a named person's agreement, recorded.

2. Confirm those documents carry every field an IRN requires

Fields that were optional on the EWB_ONLY route become required the moment the type routes to IRN.

Check: take a real document of that type from production data and run it against the e-Invoice field requirements. A hand-made sample does not count — it will have the fields precisely because you wrote it.

3. Confirm the numbering series is unique per GSTIN per fiscal year

An IRN consumes a document number permanently. Once a challan series produces IRNs, those numbers can never be reused.

Check: the series has no repeats within a GSTIN and fiscal year, and nothing in the ERP resets it mid-year.

4. Decide what happens to documents already in flight

The rule applies from the moment it exists. Decide deliberately whether the backlog is reprocessed or left on the old route, and who does it.

Check: the decision is written down and the backlog owner knows.

5. Test it in a non-production environment

Apply steps 6 to 8 there first, with real documents of that type.

Check: those documents complete end to end on the new route — not merely that the rule was accepted.

6. Read what resolves today

GET /api/admin/doc-type-routing/resolve/CHL

Check: you have recorded the current route, so you can put it back.

7. Delete the existing company rule, if there is one

DELETE /api/admin/doc-type-routing/{id}

Skip this if the type is currently on a global default — global defaults cannot be deleted, and attempting it returns 404. You override a global default; you do not remove it.

Check: GET /api/admin/doc-type-routing no longer lists a company row for that type.

8. Create the new rule

POST /api/admin/doc-type-routing
Content-Type: application/json

{ "nicDocType": "CHL", "route": "IRN", "description": "Challans require IRN for internal control" }

A 409 here means a company rule still exists — step 7 did not complete.

Check: GET /api/admin/doc-type-routing/resolve/CHL reports the new route, and the change appears in the audit trail.

9. Watch the first business day

A routing change that was wrong shows up as a wave of validation failures, not as an error at the moment of the change.

Check: quarantine volume for that document type is at its normal level, not elevated.

Validation

Check Method Pass condition
Every type in use is covered List the customer's document types against the routing table Every one has a route, default or overridden
Mapped values are correct Inspect the mapped payload for one document of each type The translated type matches the intended value exactly
Routing behaves as configured Ingest one document of each type Status matches the expected route: PENDING for the IRN route, EWB_PENDING otherwise
Overrides apply to the right company Check per company, not globally The rule appears against the intended company
Overridden types have complete data Ingest a real document of the overridden type Passes validation. Failures here mean the data is not IRN-ready
Numbering is safe Confirm the series is unique per GSTIN per financial year Confirmed by the ERP team
Tax lead endorsed it Change record Recorded

Test with real documents of each type. A hand-made sample carries the fields you thought of; a real challan carries the fields the ERP actually emits, which is the population that will fail.

Troubleshooting

Symptom Cause Action
A challan produced no IRN Correct default behaviour Only override if the business genuinely requires it
An invoice produced no IRN The mapped type is not what you expect Inspect the mapped payload. A lookup rule may be producing an unexpected value
Documents route unexpectedly after a mapping change The mapping now yields a different type value Routing reads the mapped value, not the ERP's original
A wave of quarantines after enabling an override Those documents lack fields the IRN route requires Expected. Either complete the data at source or reverse the override
An override was configured but has no effect Applied at the wrong scope, or the company does not match Confirm the rule is against the company the documents belong to
Cannot find routing in the admin console There is no screen for it Expected. Use the API described above
A second POST returns 409 A company rule already exists for that type; there is no update operation DELETE the existing rule, then POST the new one
DELETE returns 404 on a rule you can see It is a global default, not a company rule Global defaults cannot be deleted. Add a company override instead
An error tells you to configure it in Admin > Doc Type Routing The platform message names a screen that does not exist It means no rule exists for that type. Add one via the API
Duplicate rejections on a challan series after an override The series restarts, or is shared with another system Numbers are now permanently consumed. Fix the series before continuing
The tax team disputes an IRN on a document type Routing changed without their endorsement Reverse it, then decide properly. Issued IRNs cannot be withdrawn — only cancelled, and the number stays consumed
An unrecognised document type is rejected The type is absent from the routing configuration Add it deliberately; do not guess a route