Skip to content

GSTN and NIC via a GSP

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

Purpose

Explain the government-facing connection: what Complifly sends out, what it deliberately answers from its own data, what a customer is responsible for, and what happens when the provider is unavailable.

Audience

Architects, implementation consultants, support engineers. Also useful to a customer's tax lead assessing dependency risk.

Prerequisites

Reference

The chain

  Complifly  --HTTPS-->  Licensed GSP  -------->  NIC (e-Invoice, e-Way Bill)
                                       -------->  GSTN (registration data)

Complifly is not a GSP. It reaches the government through a licensed intermediary, and the customer holds the commercial relationship with that provider.

What goes out, and what does not

Operation Goes to the provider Reason
Generate a reference number Yes No local alternative
Cancel a reference number Yes Changes state at the government
Generate an e-Way Bill Yes Same
Update vehicle, extend validity, cancel Yes Same
Consolidated bill, multi-vehicle Yes Same
Fetch an issued reference number No Stored at generation, with its signed QR and payload
Print — Branded No Rendered locally from the signed invoice and QR captured at generation
Print — official NIC copy Only within 2 days of generation The government serves it for 2 days; Complifly caches it at generation so it survives. An uncached copy is unobtainable afterwards
Fetch an e-Way Bill we generated No Stored
Registration status of a counterparty Sometimes Cached with a staleness window; refreshable on demand
Identity and enterprise verification Sometimes Same
Distance between postal codes Sometimes Previously resolved distances are reused

Everything that creates or changes a government document must go out. Everything that only reads is answered locally where the answer is already held.

Why reads are answered locally

Reason Consequence
Cost Provider reads are billed per call. A lookup whose answer is stored is money spent on nothing, repeatedly
Latency Every read puts a third party on a screen's critical path
Rate limits Read traffic competes with generation, which has no alternative
Portability Every avoided read is one fewer operation a new provider must support

The operational payoff: a provider outage is a degradation, not an outage. Generation and cancellation stop; every screen backed by stored data, including printing, keeps working.

Freshness, where it matters

Some data is authoritative only at the source and does age. A counterparty's registration can be cancelled or suspended after it was last checked, and a verification result ages.

Complifly holds these 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. The window lengths are configurable — see Environment Variables — and the trade-off is explicit: shorter windows cost more and are fresher.

Data that never changes once written — a reference number, its signed QR, an e-Way Bill already generated — is never re-fetched.

The one exception is the official NIC-format print copy, which the government serves only for two days after generation. It is fetched and cached at generation time for exactly that reason; after the window closes an uncached copy cannot be obtained at all, and Branded Print is the answer.

What the customer must supply

Item Owner Note
A commercial agreement with the provider Customer Including call volumes and pricing
Sandbox credentials Customer, from the provider Before integration testing
Production credentials Customer, from the provider Before go-live, not on the day
Registration-level credential scoping Customer and provider Where the provider requires it
Source-address allow-listing Customer and network Where the provider restricts by address
Credential renewal Customer An expiry nobody owns becomes an outage

Verify: How provider call volume is metered and billed, and how consumption is visible to the customer, is not established here. Confirm before go-live. Recorded as assumption D2 in the Assumptions Register.

Behaviour during an outage

Capability During a provider outage
Sign in, browse, search Works
Ingest documents Works
Validate and correct Works
Branded Print of registered documents Works
Official NIC copy, already cached Works
Official NIC copy, not yet cached Fails
Reports and analytics Works
Generate a reference number Fails
Cancel Fails
Generate or amend an e-Way Bill Fails
Fresh verification lookups Fails; cached results still serve

Documents accumulate awaiting generation and are processed when the provider returns. The one thing to watch is the reporting window: documents cannot wait indefinitely, and a long outage close to a window boundary needs escalation rather than patience.

Rejections come from the government

A numbered rejection originates at NIC, not at Complifly and not usually at the provider. Complifly's job is to make clear which kind of failure it is and who can act — see NIC Error Codes.

Neither Complifly nor the provider can override a rejection, reopen a closed window, or release a consumed document number.

Validation

Check Method Pass condition
Provider connection works Connection test Success
Sandbox and production separated Inspect endpoints per environment Non-production points only at sandbox
Credentials scoped correctly Generate for each registration All succeed
Egress address registered Confirm with the provider Matches, including failover paths
Outage degrades gracefully Point at a wrong endpoint temporarily Local screens and Branded Print keep working
Local reads confirmed Run Branded Print with the provider unreachable Succeeds
Cache windows suit the business Review the configured windows Deliberate, not defaulted
Expiry owned Operations calendar Dates recorded with an owner

Troubleshooting

Symptom Cause Action
All government operations fail suddenly Credentials expired, or the egress address changed Check expiry, then the address the provider sees
Connection test fails on a certificate An intercepting proxy is untrusted Trust its certificate authority. The provider is not down
Some operations unavailable Provider capability Check the matrix. Temporary and permanent states differ
Provider bill higher than expected An integration polling a read with a local answer Review the calling pattern
Verification data stale Cache window longer than the business needs Shorten it, accepting the cost
Documents accumulate during an outage Expected Watch the reporting window. Escalate if a boundary approaches
A numbered rejection A government rule was broken Look it up; the fix depends on who owns it
Cancellation fails after a provider switch Old credentials withdrawn too early Restore them while live documents remain
A test document reached the government Non-production using production credentials Treat as an incident. The number is permanently consumed