E-Way Bill API Integration: GSP vs Direct NIC Access

The direct NIC connection passed sandbox testing, went live in March and ran cleanly until the data centre moved. The new firewall presented a different outbound address, NIC's whitelist still held the old three, and every e-way bill call from the ERP failed at 19:10 on a Friday with 40 trucks loading. Dispatch fell back to typing e-way bills on the portal, one at a time, until well past midnight.

Most e-way bill API outages trace back to the access model chosen at the start: who holds the client credentials, whose IP addresses NIC trusts, how the token and session key are cached, and how error codes are routed. Choosing between direct NIC access and a GST Suvidha Provider (GSP) with those facts in view, and testing the failure paths before go-live, prevents most of them.

• What this guide covers: NIC's eligibility rules for direct access, the version 1.03 authentication flow, token and key caching, throttling codes, Part B updates through the API, a worked cost comparison and a go-live checklist.
• What it leaves out: generating e-way bills from an e-invoice IRN, which our guide to IRN and e-way bill sequencing covers; this article is about the access route and the integration plumbing.

Two routes into the NIC e-way bill system and what each one hands you

Direct access gives your own system NIC-issued client credentials and puts NIC's whitelist on your IP addresses. The GSP route puts those credentials and that network path with the provider, while you still create your own API user. The APIs, payloads and validations are the same either way.

NIC's on-boarding page sets out both paths. GSPs, taxpayers and transporters wanting API access must be shortlisted in the list provided by GSTN, request sandbox credentials from the NIC API helpdesk, submit a test summary report after testing, and complete IP whitelisting before production. Once production is granted, a direct user registers through the "For API" option on the e-way bill portal; a GSP user picks "For GSP", selects the provider from a dropdown and creates its own username and password.

Branch structure matters. The on-boarding page lets a business with several places of business under the same PAN reuse the client ID and secret of its main place of business, but each GSTIN must still create its own API username and password. A twelve-state distributor therefore manages one credential pair and twelve users, and its error handling must know which GSTIN each call was made for.

NIC's conditions for direct access: volume, TLS domain and static IPs

Direct access is meant for high-volume, fully automated users. NIC's current pre-requisites page asks for automated invoice generation, around 10,000 e-way bill transactions per month per GSTIN, a TLS-secured domain, a pre-production test system and no more than three whitelisted Indian static IP addresses.

• Automated invoicing: the invoice must already be generated by a system, because the API takes structured document data, not scanned paper.
• Transaction volume: around 10,000 generations or updates per month per GSTIN; an earlier 2018 NIC manual set the bar at 1,000 activities a day, so check the live page before applying.
• Secure domain: an SSL or TLS-based domain name for the interface.
• Static IP limit: production access by whitelisting up to three Indian static IP addresses, which rules out most auto-scaling cloud egress without a fixed gateway.
• Pre-production system: a separate test environment that has exercised all API types against NIC's sandbox before the production request.

The three-address limit is the condition that bites later. High-availability designs often have more egress points than that, and cloud migrations change them. Any direct design needs a fixed egress gateway with exactly the whitelisted addresses, plus a runbook for updating NIC before a network change rather than after the first failed call.

E-way bill API integration through direct NIC access requires, on NIC's pre-requisites page, around 10,000 transactions per month per GSTIN, automated invoicing, a TLS domain and at most three whitelisted Indian static IP addresses, while CGST Rule 138(1) still applies to every consignment above ₹50,000 whichever route the ERP uses.

Authentication on version 1.03: public key, app key, SEK and token

Every session starts with one authentication call that returns two things: an auth token for the request headers and a session encryption key (SEK) for the request bodies. Getting the key handling right is most of the integration work on the direct route; on the GSP route the provider usually does it.

NIC's version 1.03 authentication endpoint at /v1.03/auth replaced the older /authenticate API, which NIC has marked deprecated. The request carries the client ID, client secret and GSTIN in headers. Its body is a JSON object with the action ACCESSTOKEN, the API username, password and a 32-character random app key; that JSON is Base64-encoded and encrypted with the e-way bill system's public key. The response returns a status, the auth token and the SEK.

// 1. Authenticate (NIC e-way bill API v1.03) - illustrative values
POST https://<nic-host>/v1.03/auth
Headers: client-id, client-secret, Gstin: 33AABCX1234K1Z9
Body:    { "Data": RSA_Encrypt( Base64( {
            "action": "ACCESSTOKEN",
            "username": "acme_api_blr",
            "password": "********",
            "app_key": "<32 random characters, new per session>" } ),
            NIC_public_key ) }

Response: { "status": "1", "authtoken": "<token>", "sek": "<encrypted SEK>" }
SEK      = AES256_Decrypt( sek, app_key )      // AES/ECB/PKCS7Padding

// 2. Cache with the expiry of the FIRST successful login
cache[gstin] = { token, SEK, expires_at: first_login_time + 360 min }
// A repeat auth call before expiry returns the same token; never move expires_at

// 3. Service call, e.g. Part B update
POST https://<nic-host>/<service path>  Headers: client-id, client-secret, Gstin, authtoken
Body: { "action": "VEHEWB", "data": AES256_Encrypt( Base64(json), SEK ) }
json = { "ewbNo": 141008683051, "vehicleNo": "KA51AB4421", "fromPlace": "HOSUR",
         "fromState": 33, "reasonCode": "1", "reasonRem": "Vehicle breakdown",
         "transDocNo": "", "transDocDate": "", "transMode": "1", "vehicleType": "R" }

Two details catch first-time builders. The SEK in the response is encrypted under the app key the caller sent, so the integration must keep that app key in memory until it has decrypted the SEK. And the GSTIN in the request header must match the GSTIN in the payload: NIC returns error 358 when they differ, which happens when one service account posts for several branches.

Why the six-hour token must be timed from the first login

An e-way bill auth token expires 360 minutes after the first successful login, and repeat logins do not extend it. Store that first expiry and renew only after it passes, or after a token error, never on a timer that resets with each call.

NIC's FAQ on the authentication page gives the example directly: authenticate at 12:00 and the token is active until 06:00; call the auth API again at 02:00 and the same token comes back, still expiring at 06:00 rather than 08:00. A cache that records the second call's time as a new issue time will keep using a dead token for two hours.

NIC e-way bill API authentication version 1.03 returns an auth token valid for 360 minutes from the first successful login and a session encryption key encrypted with the caller's 32-character app key, so an ERP or TMS token cache must keep the original expiry instead of resetting it on each call.

Throttling signals and the codes NIC uses when it blocks a caller

NIC throttles callers but does not publish a numeric quota on its API documentation pages. The integration must therefore read the signals: error 118 asks the caller to try after five minutes, and error 658 says the caller is blocked because the allowed number of requests for the period has been exceeded.

Blocking usually follows a retry storm. A token expires, every queued Part B update fails with 238, the client retries each one immediately, and within minutes thousands of calls have hit NIC with a known-bad credential. Treat 105, 106 and 238 as one event that triggers a single re-authentication, not a per-message retry, and hold the queue until the new token is in place.

• Single re-authentication: on 106 or 238, pause the queue, authenticate once, then resume; if the new token fails, stop and alert.
• Back-off on 118: wait at least the five minutes the message names before the next attempt for that GSTIN.
• Hard stop on 658: no automatic retries; page the integration owner and open the portal fallback for dispatch.
• No retries on data errors: codes in the 200 and 300 ranges describe the payload, so resending it unchanged only adds to the request count.
• Duplicate protection: error 604 means an e-way bill already exists for that document number; fetch it rather than generating again.

The general case for idempotent, replayable integrations is made in our guide to event-driven WMS, TMS and ERP orchestration, which treats the e-way bill gateway as one endpoint among many. This article narrows that down to the NIC-specific choices: which route to take, how its token behaves and which of its error codes mean stop.

Updating Part B through VEHEWB without tripping ownership errors

Part B updates are the most frequent API call for most shippers and transporters, and the most likely to fail for reasons of ownership rather than format. NIC accepts a VEHEWB update only from the generator when no transporter is assigned, or from the assigned transporter, and only while the e-way bill is active and within validity.

CGST Rule 138(5) requires the conveyance details in Part B to be updated before goods move to another conveyance, by the consignor or recipient who furnished Part A or by the transporter. The VEHEWB page enforces that in its validations. For road the vehicle number is mandatory and the transport document optional; for rail, air or ship the transport document number is required. The schema limits the vehicle number to 15 characters and the reason remark to 50.

The operational side of a vehicle change, including breakdowns and transshipment evidence, is covered in our guide to handling a vehicle change without losing the e-way bill trail. Here the concern is narrower: the API must know who owns the bill at the moment of the call, which means storing the transporter assignment on the shipment and refreshing it with a get-details call before each update.

Part B updates through the NIC VEHEWB API succeed only while the e-way bill is active and within validity, and only for the generator without a transporter or for the assigned transporter, reflecting CGST Rule 138(5), so a TMS should route errors 311, 312 and 636 to people instead of retries.

Incident trace: an evening wave lost to a misread token expiry

The sequence below combines the token rule and the throttling codes into one failure. The GSTIN, times and counts are illustrative; the error codes and token behaviour come from NIC's documentation.

• 12:00: the TMS integration authenticates for GSTIN 33AABCX1234K1Z9; NIC's token is valid until 18:00.
• 15:30: a deployment restarts the service, which calls auth again, receives the same token, and stores a new expiry of 21:30.
• 18:02: the evening wave's first VEHEWB call returns 238, invalid auth token; the client retries each of 1,400 queued updates three times without re-authenticating.
• 18:09: NIC answers 658, blocked for exceeding the allowed requests; even a fresh token now fails for that GSTIN.
• 18:40: dispatch starts manual Part B entry on the portal for 22 waiting trucks; the controlled design would have kept the 18:00 expiry, re-authenticated once at 18:02 and drained the queue normally.

Sorting error codes into re-authenticate, correct data or escalate

Each NIC error code should map to exactly one handling path, stored as configuration. Some paths are pure system rules; others need a dispatcher, a tax analyst or the transporter, with software helping them find the fix faster.

Error routing is easier to operate when failed messages carry the source evidence a person needs to fix them. Our article on triaging failed logistics integrations with source evidence describes how to hold such a queue; the e-way bill case adds a time limit, because a truck at the gate cannot wait for the next business day.

Direct versus GSP cost over 24 months, in rupees and dollars

For most shippers the GSP route is cheaper until volumes are very high, because direct access carries fixed costs for build, certification, static infrastructure and on-call support. Every figure below is an illustrative assumption for modelling, not a quote from NIC or any provider; the NIC API pages we checked list no access fee.

The break-even comes from simple arithmetic. Direct carries ₹83,000 a month of fixed cost against the GSP route's ₹18,000, a ₹65,000 gap, plus ₹15,000 a month once the extra ₹3,60,000 build cost is spread over 24 months. At an assumed ₹0.40 per call the GSP fee closes an ₹80,000 monthly gap only at about 2,00,000 calls. Direct access earns its place for control and latency reasons more often than for cost.

Downtime cost belongs in the same model. If an outage holds 22 trucks for an hour at an illustrative ₹800 per truck-hour of detention, one evening costs ₹17,600, about $200. Two such evenings a year will not decide the route, but a design that cannot change its whitelisted IPs quickly, or a provider without a tested fallback, can produce many more.

Sandbox certification and a go-live checklist for either route

Whichever route you choose, prove the failure paths in NIC's sandbox before production: token expiry, a blocked GSTIN, a Part B ownership conflict, a duplicate document and an IP change. NIC's own validations, including the 180-day document date limit and the 360-day extension limit in force since 1 January 2025, can be tested there too.

Cancellation and acceptance windows deserve a test of their own: CGST Rule 138(9) allows cancellation within 24 hours of generation if goods are not moved as declared, and Rule 138(12) deems the other party to accept the details if it does not respond within 72 hours. For more on India and US logistics data flows, see the Logistics and Supply Chain hub. If you are planning an e-way bill or wider GST integration, you can send us your requirements.