--- updatedAt: 2026-05-14T11:03:01.000Z agentTools: projectIndex: https://developer.onefinops.com/llms.txt --- # Generate EWB by IRN Generate an e-Way Bill against a previously-generated IRN. NIC IRP returns the EWB linkage; we persist it on the IRN row so subsequent Get-by-IRN returns the combined shape without another live NIC hit. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "OneFinOps API", "version": "1.0.0", "summary": "Programmatic access to the Indian GSTN portal — IRN registration, e-Way Bills, and GSP credential management.", "description": "The OneFinOps GST API lets you generate IRNs (e-invoices), manage e-Way Bills, and onboard GSP\ncredentials directly against your tenant. This reference documents every public endpoint exposed\non `api.in.onefinops.com` (production) and `sandbox-api.in.onefinops.com` (sandbox).\n\nAll endpoints are authenticated with OAuth 2.0 client credentials. See **Authentication** in the\nguides for token issuance, scope semantics, and SDK examples.\n", "contact": { "name": "OneFinOps Developer Support", "email": "developers@onefinops.com", "url": "https://onefinops.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.in.onefinops.com", "description": "Production" }, { "url": "https://sandbox-api.in.onefinops.com", "description": "Sandbox" } ], "tags": [ { "name": "E-Invoice", "description": "Generate, fetch, cancel and poll IRN registrations against the NIC IRP." } ], "security": [ { "oauth2": [] } ], "paths": { "/v1/einvoices/ewaybill": { "post": { "tags": [ "E-Invoice" ], "operationId": "generateEWayBillByIrn", "summary": "Generate EWB by IRN", "description": "Generate an e-Way Bill against a previously-generated IRN. NIC IRP returns the EWB linkage; we persist it on the IRN row so subsequent Get-by-IRN returns the combined shape without another live NIC hit.\n", "security": [ { "oauth2": [] } ], "parameters": [ { "$ref": "#/components/parameters/GstinHeader" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEWayBillByIrnRequest" } } } }, "responses": { "200": { "description": "EWB generated and linked to the IRN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEWayBillByIrnResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.0 client credentials flow. Mint your token from `login.onefinops.com` using your `ofin_live_*` (production) or `ofin_test_*` (sandbox) credentials issued from the Developer console. The realm attaches `onefinops.api` as a **default scope** to every `ofin_*` client at provision time — you do not pass `scope=...` on the token request. The minted access token carries `aud=onefinops.api` and `client_class=external_customer`.", "flows": { "clientCredentials": { "tokenUrl": "https://login.onefinops.com/realms/onefinops/protocol/openid-connect/token", "scopes": {} } } } }, "parameters": { "GstinHeader": { "in": "header", "name": "gstin", "required": true, "description": "GSTIN whose NIC IRP / EWB-portal credential authorizes the call.\nSeed each GSTIN's credential through the Developer Console.\n", "schema": { "type": "string", "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][A-Z0-9]{3}$", "minLength": 15, "maxLength": 15, "example": "05AAACG2409A1ZH" } }, "RequestIdHeader": { "in": "header", "name": "X-Request-Id", "required": false, "description": "Optional client-supplied UUID for correlation across logs and dashboards. If omitted, OneFinOps mints one and echoes it back on the response.", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Request rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Conflict": { "description": "State conflict — see `code` for the specific reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ValidationError": { "description": "Body or query failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "schemas": { "ApiError": { "type": "object", "description": "Canonical error body returned on every 4xx / 5xx response. The HTTP\nstatus carries the category — there is no `httpStatus` field in the\nbody. NIC IRP / EWB rejections come through as the top-level `code`\n(numeric NIC code or `GSP_GATEWAY_REJECT` for non-NIC vendor errors);\nthe verbatim NIC text is preserved in `details` keyed by code.\n", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. For NIC business errors this is the NIC numeric code (e.g. `\"382\"`); for our own errors it is a dotted identifier (e.g. `einvoice.cancel_window_expired`). Branch on this — never on `message`.", "examples": [ "382", "einvoice.cancel_window_expired", "validation_error", "GSP_GATEWAY_REJECT" ] }, "message": { "type": "string", "description": "Human-readable explanation. Safe to show end users, but not for programmatic logic." }, "details": { "type": "object", "description": "Optional. Keys are error codes (or field paths on 422 validation\nfailures); values are arrays of messages. For NIC errors the\nverbatim message text from NIC is preserved here under the NIC\ncode key.\n", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "examples": [ { "382": [ "You Cannot Extend as EWB can be Extended only 8 hour before or after w.r.t Validity of EWB" ] }, { "documentDetails.documentDate": [ "The document date should not be a future date." ] } ] }, "requestId": { "type": "string", "description": "Echoes the request id (X-Request-Id) for support correlation." }, "traceId": { "type": "string", "description": "W3C trace-id for distributed-tracing correlation." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC timestamp the error was generated." } } }, "GenerateEWayBillByIrnRequest": { "type": "object", "description": "Body for `POST /v1/einvoices/ewaybill`. Mirrors the NIC IRP \"Generate EWB by IRN\" payload.", "required": [ "irn", "distance" ], "properties": { "irn": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]{64}$", "description": "The 64-character IRN to attach the EWB to." }, "distance": { "type": "integer", "minimum": 0, "maximum": 4000, "default": 0, "description": "Consignment distance in km, used by NIC to compute EWB validity. Pass `0` to let NIC auto-calculate the pin-to-pin road distance from the source and destination pincodes (recommended when the exact road distance is unknown). Any non-zero value is validated against NIC's pin-to-pin reference and is rejected if it deviates beyond NIC's tolerance (≈10% above the calculated value) with \"The distance between the pincodes given is too high\". For a small number of pincode pairs NIC has not mapped, `0` is rejected with \"The distance between the given pincodes are not available in the system. Please provide distance\". Retry with the actual road distance (a positive value up to 4000 km; NIC accepts your value on these unmapped routes). The field is mandatory; omitting it returns \"Invalid Approximate Distance\". The applied distance is returned on generation and on Get E-Way Bill.", "example": 1859 }, "transportMode": { "type": "string", "enum": [ "1", "2", "3", "4" ], "nullable": true, "description": "1=Road, 2=Rail, 3=Air, 4=Ship.", "example": "1" }, "transporterId": { "type": "string", "minLength": 15, "maxLength": 15, "nullable": true, "description": "Transporter GSTIN or NIC TRANSIN. Required when `vehicleNumber` is not supplied (Part-A only)." }, "transporterName": { "type": "string", "nullable": true }, "transportDocumentNumber": { "type": "string", "nullable": true }, "transportDocumentDate": { "type": "string", "format": "date", "nullable": true }, "vehicleNumber": { "type": "string", "nullable": true, "description": "Vehicle number — required for road movements when generating Part-B in the same call.", "example": "KA01AB1234" }, "vehicleType": { "type": "string", "enum": [ "R", "O" ], "nullable": true, "description": "`R` Regular or `O` Over-Dimensional Cargo." } } }, "GenerateEWayBillByIrnResponse": { "type": "object", "description": "Response for `POST /v1/einvoices/ewaybill`. Mirrors the NIC IRP \"Generate EWB by IRN\" result.", "required": [ "ewbNumber" ], "properties": { "ewbNumber": { "type": "integer", "format": "int64", "description": "The 12-digit e-Way Bill number issued by the IRP.", "example": 141012047424 }, "ewbDate": { "type": "string", "format": "date-time", "nullable": true, "description": "IRP EWB generation timestamp (UTC)." }, "ewbValidTill": { "type": "string", "format": "date-time", "nullable": true, "description": "EWB validity expiry timestamp (UTC). NIC verbatim — `ewbValidTill`, not `ewbValidUntil`." } } } } } } ```