OptoSoft Developers API – India

Introduction

The OptoSoft REST API gives your software direct, programmatic access to an optical store’s data — customers and their prescriptions, sales orders, GST invoices, receipts, stock and daily takings. It is the same API used by the OptoSoft web application and the OptoSoft Android POS app, so anything those products can do, your integration can do too.

Typical uses include syncing customers into a CRM or marketing platform, pushing orders in from a website or marketplace, pulling invoice data into an accounting package such as Tally or Zoho Books, feeding a business-intelligence dashboard, or building a custom in-store app on top of your existing OptoSoft data.

Postman collection

Every endpoint on this site is packaged as a ready-to-import Postman collection — all 85 requests, grouped into the same 8 modules, with pre-filled example bodies, 218 saved response examples (success and error cases) and a login script that captures your token automatically.

Import and run in under a minute

1. Download the file above, then in Postman choose Import and drop it in.
2. Open the collection’s Variables tab and set username and password.
3. Run 01 Authentication & Account → Login. Its test script stores the JWT in {{token}} for you.
4. Set companyId, branchId and yearId (from Get my profile and List financial years), then send any request.

Collection-level auth is already set to Bearer {{token}}, so every request except login inherits it. Encrypted identifiers have their own enc* variables — paste real values in as you obtain them from earlier responses (see Encrypted identifiers).

Base URL

All endpoints are served over HTTPS from a single host. Every path in this reference is relative to it.

https://api.opto-soft.com

So POST /api/Auth/login means POST https://api.opto-soft.com/api/Auth/login. Plain HTTP is not supported. The machine-readable OpenAPI 3.0 specification is published at /swagger/v1/swagger.json.

Authentication

The API uses JWT bearer tokens. Exchange your OptoSoft username and password for a token once, then send that token on every subsequent call.

1. Request a token

curl -X POST https://api.opto-soft.com/api/Auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "your-optosoft-username",
    "password": "your-password"
  }'

2. Send it on every request

curl https://api.opto-soft.com/api/Orders/cancellation-reasons \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Every endpoint documented here requires the Authorization header. A missing, malformed or expired token returns 401 Unauthorized. Full details are on the Authentication page.

Company, branch and year context

OptoSoft is multi-tenant and multi-branch, and Indian accounting is organised by financial year. Most search and save requests therefore carry three scoping fields:

Note that these are typed inconsistently across the API: some endpoints take them as numbers (int64), others as encrypted strings. Each endpoint’s field table states which form that endpoint expects — follow it exactly.

Encrypted identifiers

Many request and response fields are opaque encrypted identifiers rather than plain numbers. You will see this wherever a schema name is prefixed Encrypted, and wherever an ID field is typed string instead of int64 — for example customerID, salesOrderID and itemTypeID.

The rule for handling them is simple:

• Never construct one yourself and never assume it is a number in disguise.
• Read it from a previous response and echo it back verbatim, including case.
• Do not URL-encode or re-encode it beyond normal query-string escaping.
• Treat it as opaque and unstable — do not persist it as a long-term primary key or parse meaning out of it.

Some list responses return both forms, such as EncryptedInvoiceListDto which carries an encrypted id alongside a numeric plainId. Where both exist, use the encrypted id for follow-up API calls and keep plainId only for your own reconciliation.

In the wire format they appear as Base64-like strings, for example "CustomerID": "Q2ZQdGhSZVhBaVlXTnpaWFF3TWk0d01B". OptoSoft confirms these are AES-encrypted values.

Pagination

The API uses two different paging conventions depending on the module. Check the field table for the endpoint you are calling.

Paged responses also come in two shapes. Almost every paged endpoint returns Items / Total / PageNumber / PageSize:

{
  "Items": [
    { "...": "one object per record" }
  ],
  "Total": 248,
  "PageNumber": 1,
  "PageSize": 25
}

The one exception is POST /api/Invoice/List, which uses TotalRows / Data instead:

{
  "TotalRows": 132,
  "Data": [
    { "...": "one object per record" }
  ]
}

Response envelopes

Across the 60 endpoints with a published response there are six distinct top-level shapes. This is the single most common source of integration bugs, so check the endpoint page before you model anything:

Response conventions

Request and response field naming differ, which catches most integrations out on day one:

Two further quirks worth handling defensively:

• Some booleans are returned as strings — for example "IsActive": "true" on customer rows, while "IsCurrentYear": false is a real boolean elsewhere.
• Dates appear both as ISO timestamps ("2024-01-15T09:15:00") and as display strings ("15/01/2024", dd/MM/yyyy) depending on the field.

Sort order is controlled by an orderBy string (a column name, optionally followed by DESC). Omit it to accept the module default.

Errors

Error bodies are not uniform, and they are not RFC 7807 problem details despite the OpenAPI specification declaring a ProblemDetails schema. In practice there are two shapes.

Validation failures (400) return a JSON object:

{
  "success": false,
  "message": "Mobile No is required."
}

Auth and not-found failures (401, 404) return a bare JSON string — not an object:

"No logged in please login to get the access."

"Customer not found."

Successful save operations return an acknowledgement carrying the new entity’s encrypted id:

{
  "success": true,
  "message": "Customer saved successfully.",
  "customerID": "Q2ZQdGhSZVhBaVlXTnpaWFF3TWk0d01B"
}

Rate limits and fair use

No hard rate limit is published in the OpenAPI specification. In practice, treat the API as a business system rather than a bulk-export pipe:

• Keep sustained traffic under roughly 60 requests per minute per branch.
• Reuse a single bearer token across calls rather than logging in per request.
• Page through large result sets instead of requesting very large pageSize values.
• Poll search endpoints on a date range (every few minutes), not in a tight loop.
• Back off exponentially on 500 responses.

If you need a higher sustained throughput for a migration or a nightly sync, let us know in advance.

API reference by module

85 endpoints are documented across 8 modules. If you are starting from scratch, read Authentication first, then Customers & Prescriptions.

Versioning and change policy

The current specification version is v1. OptoSoft reviews the live OpenAPI specification against this documentation every month and records additions, removals and field changes below.

Treat new fields appearing in a response as non-breaking — parse defensively and ignore properties you do not recognise, so that an additive change never breaks your integration.

Frequently asked questions