Guides
  1. Getting Started

Sandbox vs Production

OneFinOps runs sandbox and production as logically separated environments sharing one login (Keycloak realm). The API host you call decides which environment runs the request. Tokens minted for an ofin_test_* client target sandbox; tokens minted for an ofin_live_* client target production.

At a glance

SandboxProduction
API hosthttps://sandbox-api.in.onefinops.comhttps://api.in.onefinops.com
Token endpointhttps://login.onefinops.com/realms/onefinops/protocol/openid-connect/tokenhttps://login.onefinops.com/realms/onefinops/protocol/openid-connect/token
OAuth client-id prefixofin_test_*ofin_live_*
UpstreamNIC IRP / EWB sandboxesLive NIC IRP / EWB
DataTest data; can be reset by NICPersistent, legally binding
Signed JWSSigned by NIC's sandbox certificateSigned by NIC's production certificate

Behavioural differences

A handful of NIC-side behaviours differ between their sandbox and live portals. The OneFinOps API surface is identical, but the data you get back reflects these:

  • Signed invoice and QR. Signed in sandbox with NIC's sandbox certificate — do not present these in production accounting systems. Verifiers configured for the production NIC public key will reject them.
  • Sandbox GSTINs are pre-allocated. Production accepts any valid GSTIN you've enrolled. Sandbox accepts only NIC's published test GSTINs (e.g. 36AMBPG7773M002 for IRP, 05AAACG2409A1ZH for EWB).
  • IRP and EWB enrolment are disjoint in sandbox. No sandbox GSTIN is enrolled on both portals. The practical effect:
    • Combined IRN + EWB in one call (/v1/einvoices/generate with an eWayBill block) accepts the request and returns the IRN, but ewbNumber is null because NIC sandbox can't issue the linked EWB.
    • To exercise EWB flows in sandbox, use the two-step variant: register the IRN, then call /v1/ewaybills/generate with the returned irn using an EWB-enrolled sandbox GSTIN.
    • In production, both portals are enrolled against the same business GSTIN, so the combined call returns the full IRN + EWB response.
  • Validity windows are honoured in both. 24-hour IRN cancellation, 24-hour EWB cancellation, 72-hour EWB rejection — sandbox does not extend these.

What they share

  • Identical request and response shapes.
  • Identical error codes and HTTP status semantics.
  • Same OAuth scope (onefinops.api) and the same login.

Promotion checklist

Before flipping your integration to production:

  1. Provision a production OAuth client from the Live tab in the Developer hub.
  2. Seed production credentials for every GSTIN you'll file under — both IRP and EWB portal credentials, separately. See GSP credentials overview.
  3. Move secrets out of build artefacts. Use a secrets manager. Never embed the client secret in a frontend or mobile app.
  4. Switch the API host to api.in.onefinops.com and the client to your ofin_live_* client id / secret.
  5. Set up alerting on failed IRN / EWB submissions on your side.

Watch your error logs in production

NIC actively rate-limits and can suspend an API user's portal access if it sees a sustained pattern of invalid requests. This is enforced at the GSTIN level on NIC's side — once your portal credential is suspended, every call from OneFinOps against that GSTIN starts failing and the only recovery is to contact NIC support.

What "invalid pattern" looks like to NIC:

  • Repeatedly submitting bodies that fail validation (wrong checksums, invalid GSTINs, bad financial year).
  • Aggressive retries of an already-failed request without fixing the underlying data.
  • Hammering NIC at peak filing times with calls that NIC's portal rejects upfront.

Practical guidance:

  • Treat 4xx responses as data problems, not transport problems. Fix the source data before resubmitting. Never put a 422 or a 502 from NIC into a tight retry loop.
  • Use sandbox for your shakedown. Catch validation issues, GSTIN-format mistakes, and arithmetic mismatches in sandbox-api.in.onefinops.com before pointing at production.
  • Monitor your error rate by GSTIN. A spike in 4xx for a single GSTIN is an early warning. Pause traffic for that GSTIN until you've fixed the root cause.
  • Honour rate-limit responses. When OneFinOps returns 429 (or NIC throttles us), back off exponentially. Retrying tight makes the throttle window longer.

A clean error pipeline on your side is the difference between a brief incident and an account suspension that takes days to unwind.

Where to next