Quickstart

This walkthrough takes you from zero to a registered IRN in sandbox. Same flow works in production once you've provisioned a live OAuth client and seeded a live IRP credential.

Prerequisites

Before you start, make sure you have:

A OneFinOps account with GST access enabled. Sign up at onefinops.com and contact your account manager if GST is not visible on the plan.
A Sandbox OAuth client (clientId + clientSecret). Issue one from Developer hub → API clients → Sandbox in the app.
An IRP sandbox credential seeded against a test GSTIN. NIC publishes a set of sandbox GSTINs (for example 36AMBPG7773M002) — use any of these. See Set up IRN credentials for the upsert call.

1. Mint an access token

Sandbox and production share the same auth server. The host you call decides which environment the token is used against.

curl -X POST 'https://login.onefinops.com/realms/onefinops/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=ofin_test_<your-client-id>' \
  -d 'client_secret=<your-client-secret>'

Response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 900,
  "token_type": "Bearer",
  "scope": "onefinops.api"
}

Tokens last 15 minutes. Cache them — never mint a fresh token per call.

2. Generate an IRN

POST /v1/einvoices/generate registers the invoice on NIC IRP and returns the IRN plus the signed invoice + QR.

curl -X POST 'https://sandbox-api.in.onefinops.com/v1/einvoices/generate' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'gstin: 36AMBPG7773M002' \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: 9b8b3f8a-quickstart-001' \
  -d '{
    "documentDetails": {
      "type": "INV",
      "number": "INV/2026/00001",
      "date": "2026-05-14"
    },
    "transactionDetails": {
      "taxScheme": "GST",
      "supplyType": "B2B"
    },
    "seller": {
      "gstin": "36AMBPG7773M002",
      "legalName": "Acme Pvt Ltd",
      "address1": "Plot 1, IT Park",
      "location": "Hyderabad",
      "pincode": 500032,
      "stateCode": "36"
    },
    "buyer": {
      "gstin": "02AMBPG7773M002",
      "legalName": "Globex Pvt Ltd",
      "address1": "Plot 9, Industrial Area",
      "location": "Solan",
      "pincode": 173212,
      "stateCode": "02",
      "placeOfSupplyStateCode": "02"
    },
    "items": [{
      "serialNumber": "1",
      "productDescription": "Consulting services",
      "isService": "Y",
      "hsnCode": "998314",
      "quantity": 1,
      "unit": "NOS",
      "unitPrice": 10000,
      "totalAmount": 10000,
      "assessableAmount": 10000,
      "gstRate": 18,
      "igstAmount": 1800,
      "totalItemValue": 11800
    }],
    "valueDetails": {
      "assessableValue": 10000,
      "igstValue": 1800,
      "totalInvoiceValue": 11800
    }
  }'

Response:

{
  "irn": "a1b2c3d4e5f6...",
  "ackNumber": 112324567890123,
  "ackDate": "2026-05-14T11:42:18.000Z",
  "status": "ACT",
  "signedInvoice": "eyJhbGciOi...",
  "signedQRCode": "eyJhbGciOi...",
  "message": "E-Invoice generated successfully"
}

Save the irn against your invoice record. The signed JWS blobs (signedInvoice, signedQRCode) are large — you don't need to keep them indefinitely; refetch when you need them.

Duplicate submissions. If you re-submit the same seller.gstin + document type + document number + financial year, NIC returns the existing IRN with infoCode: "DUPIRN" and message: "2150 : Duplicate IRN". Check infoCode rather than parsing message if you need to detect replays programmatically.

3. Fetch it back

curl 'https://sandbox-api.in.onefinops.com/v1/einvoices/irn?irn=<the-64-char-irn>' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'gstin: 36AMBPG7773M002'

Same shape as the generate response, minus the signed-JWS blobs (those are returned at registration; refetch endpoints don't echo them by default).

4. Render the QR for printing

curl 'https://sandbox-api.in.onefinops.com/v1/einvoices/qrimage?irn=<the-64-char-irn>&width=300&height=300' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'gstin: 36AMBPG7773M002' \
  --output qr.png

Returns the signed QR as a PNG, sized to the requested width/height. Place this on the printed invoice — it's the form NIC requires.

Where to next

Authentication — token lifecycle, refresh strategy, client-credentials best practices.
Generate an IRN — the full lifecycle, including cancellation and B2C / export variants.
Generate an EWB — issue an E-Way Bill (standalone or linked to an IRN).
Errors — full error code reference.