Skip to content

GSP Abstraction

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

Purpose

Explain how Complifly reaches the government systems through a licensed GST Suvidha Provider, why that provider is deliberately replaceable, what the three capability states mean for a feature you can or cannot use, and how documents already issued keep working when a tenant changes provider.

Audience

Solution architects, implementation consultants, support engineers. Anyone asked "can we switch provider?" or "why is this button unavailable for us?".

Prerequisites

Reference

Why there is an abstraction at all

Complifly is not a GSP. Every call to NIC or GSTN goes through a licensed intermediary. Rather than binding to one, Complifly defines a provider-neutral set of operations and implements one adapter per GSP. The tenant is assigned a provider; the rest of the platform does not know which.

That buys three things:

  • Commercial leverage. A tenant can move provider without re-implementing the platform.
  • Continuity. A provider outage or contract lapse is a configuration change, not a rebuild.
  • Honest feature availability. Providers genuinely differ. The abstraction makes the difference explicit and testable rather than a surprise at go-live.

Live providers

Provider Status
Webtel Live adapter, in production use
Masters India Live adapter, in production use

Additional providers can be declared for evaluation without an adapter. A declared provider with no adapter is never routable — the platform refuses to send traffic to code that does not exist, so an accurate matrix cannot cause a misrouted call.

Verify: Which providers a given customer may be assigned is a commercial matter. Confirm against your contract. Recorded as assumption D4 in the Assumptions Register.

Capability: three states, not two

For each operation, a provider is in one of three states. The distinction between the two negative states is not cosmetic — it decides whether skipped work goes onto a worklist to be redone later.

State Meaning What the product does What you should do
SUPPORTED The adapter implements it and the provider offers it Feature available Use it
NOT_SUPPORTED The provider has no such endpoint, or this adapter does not implement it. Permanent Feature hidden Plan around it; do not wait
PENDING_VENDOR The endpoint has been requested from the vendor and the specification has not arrived. Temporary Feature disabled and labelled as pending; anything skipped because of it is recorded Track it. Work skipped now must be redone when it flips

The reason PENDING_VENDOR exists as its own state is a real failure it prevents. Suppose a party master is created while a verification capability is pending. That record does not fix itself when the endpoint ships — it stays unverified forever unless something goes back for it. It can only be found again if the reason it was skipped was recorded precisely at the time. PENDING_VENDOR is what makes the eventual re-verification sweep a query rather than a guess.

Operation classes: which provider services a call

A separate question from can this provider do it is which provider should service this call. Three classes:

Class Definition Routes to
Creating Brings a new document into existence — generate an IRN, generate a standalone e-Way Bill, generate a consolidated bill The tenant's current provider
Continuing Acts on a document that already exists — cancel, print, extend validity, update vehicle, update transporter The provider stamped on that document
Utility A lookup with no document behind it — distance, GSTIN status, PAN or Udyam verification The tenant's current provider

The capability matrix

This is the table What a provider switch does and does not change tells you to compare. It is generated from the same module the router reads at runtime, so it describes what each adapter actually implements — not what the vendor sells, and not what a design document once claimed.

Read it with the routing column, not without it. A Continuing operation is answered by the provider stamped on the document, so a No in that row means the feature is unavailable for documents that provider created — regardless of which provider you are assigned to today. That is the practical consequence of provenance routing, and it is why the matrix matters most at the moment you are considering a switch.

Operation Routing Webtel Masters India
generateIrn
Generate IRN		 Creating Yes Yes
generateEwbDoc
Generate e-Way Bill without an IRN		 Creating Yes Yes
generateConsolidatedEwb
Generate consolidated bill		 Creating Pending vendor Yes
cancelIrn
Cancel IRN		 Continuing Yes Yes
getIrn
Fetch e-invoice by IRN		 Continuing No Yes
printIrn
Print e-invoice		 Continuing Yes Yes
generateEwbByIrn
Generate e-Way Bill from an IRN		 Continuing Yes Yes
cancelEwb
Cancel e-Way Bill		 Continuing Yes Yes
updateVehicle
Update vehicle (Part-B)		 Continuing Yes Yes
extendValidity
Extend validity		 Continuing Yes Yes
updateTransporterId
Update transporter		 Continuing No Yes
getEwb
Fetch e-Way Bill		 Continuing No Yes
printEwb
Print e-Way Bill		 Continuing Yes Yes
updateConsolidatedEwbPartB
Update consolidated Part-B		 Continuing Yes Yes
regenerateConsolidatedEwb
Regenerate consolidated bill		 Continuing Yes Yes
initiateMultiVeh
Initiate multi-vehicle movement		 Continuing Yes Yes
addMultiVehDetail
Add a vehicle to a group		 Continuing Yes Yes
changeMultiVehDetail
Change a vehicle in a group		 Continuing Yes Yes
rejectEwbOtherParty
Reject another party’s bill		 Utility Yes Yes
getEwbByOtherParty
List bills raised against us		 Utility Yes No
getDistance
PIN-to-PIN distance		 Utility Yes Yes
getGstinStatus
GSTIN registration status		 Utility Yes Yes
getGstinDetailsWebApi
GSTIN details		 Utility Yes Yes
getPanCaptcha
PAN captcha		 Utility Yes No
validatePAN
Validate PAN		 Utility Yes No
validatePanWebApi
Validate PAN (Web API)		 Utility Yes Yes
verifyUdyamWebApi
Verify Udyam registration		 Utility Yes Yes
decryptSignedData
Decrypt signed data		 Utility Yes No

28 operations across 2 providers. Generated from services/GSP/capabilities.js — do not edit this table by hand; run node tools/docs/gen-capability-matrix.js --write.

Declared but not available in this build: MasterGST, Quicko, Trust Fintech, CDSL, PwC, BDO, ClearTax. These appear in the capability map so the provider-agnostic design is inspectable, but no adapter exists for them and they cannot be selected. If one of these is your preferred GSP, that is a roadmap conversation, not a configuration setting.

Provenance, and the trap it avoids

Every document carries a stamp recording which provider issued it. Continuing operations follow that stamp and ignore the tenant's current assignment.

Without this, a provider switch would break every document already in flight. Consider: a tenant generates 500 IRNs through provider A, switches to provider B, then cancels one of the 500. Sent to B, the cancellation fails — B has never heard of that IRN — and it typically fails as a confusing authentication error rather than a clear "wrong provider".

Two operations look like they should be creating and are in fact continuing, which is worth knowing because it explains behaviour that otherwise seems inconsistent:

  • Generating an e-Way Bill from an IRN produces a new bill, but it is raised against an existing IRN, and only the provider that issued that IRN can do it.
  • Initiating a multi-vehicle movement creates a group, but the group hangs off an e-Way Bill that already exists.

The practical rule for an administrator: switching provider affects new documents only. Everything already issued continues to be serviced by its original provider, indefinitely, without any action from you.

What a provider switch does and does not change

Effect
New documents Go to the new provider from the moment the change takes effect
Existing documents Continue to be serviced by their original provider
Feature availability May change — compare the capability matrices before switching
Historical evidence Unchanged. IRNs, signed QR codes and stored payloads are immutable
Credentials Both providers' credentials must remain valid while any document from the old provider can still be acted on

That last row is the one most often missed. Decommissioning the old provider's credentials immediately after a switch strands every document it issued.

Reads are answered locally wherever possible

A design rule runs through the platform: any operation that reads data is served from Complifly's own store if the answer is already held, and only reaches the provider when it genuinely cannot be.

The reasoning is practical, not architectural purity:

  • Cost. Provider reads are billed per call. A lookup whose answer is already stored is money spent repeatedly on nothing.
  • Latency and blast radius. Every read puts a third party on the critical path of a screen whose data Complifly already owns.
  • Rate limits. Read traffic competes with calls that have no local alternative — IRN generation, e-Way Bill generation, cancellation.
  • Portability. Every avoided read is one fewer operation a new provider must support.

The consequence for operations: a provider outage does not take the product down. Documents cannot be generated or cancelled, but every screen backed by stored data keeps working, including printing.

Some data is authoritative only at the source and does age — a counterparty's GSTIN registration status can be cancelled or suspended after it was last checked. Where freshness matters, the platform holds a cached result with a staleness window and allows an on-demand refresh, rather than either serving stale data silently or paying for a call on every page view.

Validation

Check Method Expected
Provider assigned Admin console, GSP configuration Exactly one active provider per tenant
Credentials work Run the built-in connection test Success. Do this before go-live, not during it
Capabilities understood Review the capability matrix for the assigned provider Every operation the business needs is SUPPORTED. Anything PENDING_VENDOR has a tracked owner and a workaround
Provenance is being stamped Generate a test document; inspect its provider stamp The stamp names the provider that issued it
Continuing operations follow provenance After a provider switch in a test tenant, cancel a document issued by the old provider Succeeds, having been routed to the original provider
Local reads confirmed Disconnect the provider in a test environment and open a document, then print it Both work. Only generation and cancellation fail

Troubleshooting

Symptom Cause Action
A feature is unavailable although the provider advertises it Capability is NOT_SUPPORTED or PENDING_VENDOR for this adapter Check the state. PENDING_VENDOR is tracked and temporary; NOT_SUPPORTED needs a workaround
Cancellation fails with an authentication error after switching provider Routed to the current provider instead of the issuing one Provenance should prevent this. If it recurs, capture the document identifier and escalate — this is a routing defect, not a credential problem
e-Way Bill from an IRN fails right after a provider switch Correctly routed to the issuing provider, whose credentials have been withdrawn Restore the old provider's credentials until no live document from it remains
Everything fails at the provider, all at once Credentials expired, IP allow-list changed, or provider outage Run the connection test; check the provider's status channel. See GSP Configuration
Verification results look out of date Served from cache within its staleness window Force a refresh if the currency genuinely matters
Provider call volume is higher than expected An integration is polling a read that could be served locally Review the calling pattern. Reads with a local answer should not go out