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 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.

Pagination

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

Paged responses wrap the rows in an envelope carrying the unfiltered total, so you can compute the number of pages:

{
  "totalRows": 248,
  "data": [
    { "...": "one row per record" }
  ]
}

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

Errors

Errors are returned as RFC 7807 problem details with the appropriate HTTP status code:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "yearID is required.",
  "instance": "/api/Invoice/List"
}

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