External Data API

Overview

The External Data API exposes EqomOS catalogue and order master data to authorised partner systems ("clients"). It is read-only (HTTP GET only), returns JSON, and is designed for both full extracts and lightweight incremental syncs.

• REST + JSON over HTTPS (TLS 1.2+). All traffic is encrypted in transit.
• HMAC request signing — every request is cryptographically signed; your secret never travels on the wire.
• Per-client authorisation — each client is granted access to specific APIs with its own page-size, fetch and rate limits.
• Paginated & incremental — page through large datasets and fetch only what changed since your last sync.
• Predictable errors — every error returns a machine-readable code and a human-readable error message.

Base URL & environments

All API endpoints are served under a single versioned base path:

Onboarding & credentials

Access is granted per client. During onboarding you receive two values:

You are also told which APIs you are granted, and your per-API limits (page size, max records per fetch, requests per minute). To request access, additional APIs, or a secret rotation, contact your EqomOS account manager.

Authentication — HMAC request signing

Every request must be signed with HMAC-SHA256. The server recomputes the signature and rejects any request that does not match, is too old, or replays a previous request. This protects against tampering and replay attacks even though your secret is never transmitted.

Required headers

The canonical string

Build a string by joining these six elements with the newline character \n, in this exact order:

HTTP_METHOD            (uppercase, e.g. GET)
REQUEST_PATH           (e.g. /api/external/v1/categories — path only, no host, no query)
CANONICAL_QUERY        (see below; empty string if no query params)
SHA256_HEX(body)       (lowercase hex SHA-256 of the request body)
X-Timestamp            (the same value sent in the header)
X-Nonce                (the same value sent in the header)

Notes:

• Body hash: all endpoints are GET with an empty body, so the body hash is always the SHA-256 of the empty string:
  e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
• CANONICAL_QUERY: take each query parameter as key=value, percent-encode both key and value per RFC 3986 (unreserved characters A–Z a–z 0–9 - . _ ~ are left as-is), sort the encoded key=value pairs lexicographically, and join them with &. If there are no query parameters, use an empty string.
• The X-Timestamp and X-Nonce in the canonical string must be byte-for-byte identical to the header values.

Signing steps

1. Generate X-Timestamp (epoch seconds) and a fresh random X-Nonce.
2. Build the canonical string as above.
3. Compute signature = Base64( HMAC_SHA256( canonicalString, secret ) ).
4. Send the request with the four headers; put signature in X-Signature.

Signing — code samples

The samples below call GET /api/external/v1/categories?isFullList=1&page=0&pageSize=50. Replace the placeholder credentials with the ones issued to you.

cURL + OpenSSL (bash)

TOKEN_ID="eqc_exampleClientId123"
SECRET="EXAMPLE_SECRET_DO_NOT_USE"
METHOD="GET"
PATH="/api/external/v1/categories"
QUERY="isFullList=1&page=0&pageSize=50"     # already sorted by encoded key=value
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"  # sha256("")
CANON=$(printf '%s\n%s\n%s\n%s\n%s\n%s' "$METHOD" "$PATH" "$QUERY" "$BODY_HASH" "$TS" "$NONCE")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)

curl -sS "https://mdm.eqomos.com${PATH}?${QUERY}" \
  -H "X-Client-Id: $TOKEN_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIG"

Python 3

import time, os, hmac, hashlib, base64, requests
from urllib.parse import quote, unquote

BASE   = "https://mdm.eqomos.com"
TOKEN  = "eqc_exampleClientId123"
SECRET = "EXAMPLE_SECRET_DO_NOT_USE"
EMPTY  = hashlib.sha256(b"").hexdigest()

def canonical_query(q):
    if not q: return ""
    pairs = []
    for part in q.split("&"):
        k, _, v = part.partition("=")
        pairs.append(quote(unquote(k), safe="-._~") + "=" + quote(unquote(v), safe="-._~"))
    return "&".join(sorted(pairs))

def get(path, query=""):
    ts    = str(int(time.time()))
    nonce = os.urandom(16).hex()
    canon = "\n".join([ "GET", path, canonical_query(query), EMPTY, ts, nonce ])
    sig   = base64.b64encode(hmac.new(SECRET.encode(), canon.encode(), hashlib.sha256).digest()).decode()
    headers = { "X-Client-Id": TOKEN, "X-Timestamp": ts, "X-Nonce": nonce, "X-Signature": sig }
    url = BASE + path + (("?" + query) if query else "")
    return requests.get(url, headers=headers)

resp = get("/api/external/v1/categories", "isFullList=1&page=0&pageSize=50")
print(resp.status_code, resp.json())

Node.js

const crypto = require("crypto");

const BASE = "https://mdm.eqomos.com";
const TOKEN = "eqc_exampleClientId123";
const SECRET = "EXAMPLE_SECRET_DO_NOT_USE";
const EMPTY = crypto.createHash("sha256").update("").digest("hex");
const pct = s => encodeURIComponent(s).replace(/[!*'()]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase());

function canonicalQuery(q) {
  if (!q) return "";
  return q.split("&").map(p => {
    const [k, v = ""] = p.split("=");
    return pct(decodeURIComponent(k)) + "=" + pct(decodeURIComponent(v));
  }).sort().join("&");
}

async function get(path, query = "") {
  const ts = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(16).toString("hex");
  const canon = ["GET", path, canonicalQuery(query), EMPTY, ts, nonce].join("\n");
  const sig = crypto.createHmac("sha256", SECRET).update(canon).digest("base64");
  const url = BASE + path + (query ? "?" + query : "");
  const res = await fetch(url, { headers: {
    "X-Client-Id": TOKEN, "X-Timestamp": ts, "X-Nonce": nonce, "X-Signature": sig } });
  console.log(res.status, await res.json());
}

get("/api/external/v1/categories", "isFullList=1&page=0&pageSize=50");

Java 11+

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.*;

String base = "https://mdm.eqomos.com", token = "eqc_exampleClientId123", secret = "EXAMPLE_SECRET_DO_NOT_USE";
String path = "/api/external/v1/categories", query = "isFullList=1&page=0&pageSize=50";
String emptyBody = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"; // sha256("")
String ts = String.valueOf(System.currentTimeMillis() / 1000L);
String nonce = UUID.randomUUID().toString().replace("-", "");
String canon = String.join("\n", "GET", path, query, emptyBody, ts, nonce); // query already sorted+encoded
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String sig = Base64.getEncoder().encodeToString(mac.doFinal(canon.getBytes(StandardCharsets.UTF_8)));
HttpRequest req = HttpRequest.newBuilder(URI.create(base + path + "?" + query))
    .header("X-Client-Id", token).header("X-Timestamp", ts)
    .header("X-Nonce", nonce).header("X-Signature", sig).GET().build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.statusCode() + " " + res.body());

Common parameters

These query parameters are accepted by most endpoints. All are optional.

Endpoint-specific filters (e.g. productid, skuid, supplierskucode, orderRef) are documented under each API.

Pagination & limits

Results are paginated. Iterate by increasing page until hasNext is false.

• pageSize must not exceed your client's maximum page size. A request above the cap returns 400 PAGE_SIZE_EXCEEDED.
• A single fetch never returns more than your client's max records per fetch cap.
• If you omit pageSize, your client's configured default is used.

Incremental sync

To keep a local copy in sync efficiently, do a one-time full load and then poll for changes:

1. Initial load: call with isFullList=1 and page through all results. Record the time you started the sync.
2. Incremental: on each later run, call with isFullList=0&syncDate=<last sync time>. You receive only records changed on/after syncDate.
3. After a successful run, store the new sync time for the next call.

Response envelope

All list endpoints return the same paginated envelope:

{
  "data": [ /* array of records for this page */ ],
  "page": 0,
  "pageSize": 50,
  "totalRecords": 124,
  "totalPages": 3,
  "hasNext": true
}

Common field conventions used inside records:

Errors & status codes

Errors return a JSON body with a machine-readable code and a human error message:

{ "error": "Request signature verification failed.", "code": "INVALID_SIGNATURE" }

Rate limiting

Each client has a per-minute request limit per API. Exceeding it returns 429 RATE_LIMITED. Build a backoff (e.g. wait until the next minute, or exponential backoff with jitter) and avoid bursty parallel calls. For large extracts, page sequentially rather than firing many pages concurrently.

API reference

All endpoints are GET, require the four authentication headers, and return the paginated envelope. Only finalised master data is returned.

{
  "data": [
    { "id": 124, "supplierId": 7, "categoryCode": "ELEC", "categoryName": "Electronics",
      "parentCode": null, "level": 0, "path": "Electronics",
      "mappedCategoryId": 9001, "status": "SYNCED", "modifiedAt": "2026-06-01T10:15:00" },
    { "id": 127, "supplierId": 7, "categoryCode": "ANDROID", "categoryName": "Android Phones",
      "parentCode": "SMART", "level": 3,
      "path": "Electronics > Phones > Smartphones > Android Phones",
      "mappedCategoryId": 9004, "status": "SYNCED", "modifiedAt": "2026-06-01T10:16:20" }
  ],
  "page": 0, "pageSize": 50, "totalRecords": 6, "totalPages": 1, "hasNext": false
}

{
  "data": [
    { "id": 51, "supplierId": 7, "brandCode": "ACME", "brandName": "Acme",
      "mappedBrandId": 3300, "logoUrl": "https://cdn.example.com/brands/acme.png",
      "status": "SYNCED", "modifiedAt": "2026-05-30T08:00:00" }
  ],
  "page": 0, "pageSize": 50, "totalRecords": 1, "totalPages": 1, "hasNext": false
}

{
  "data": [
    { "supplierId": 7, "skuCode": "ACME-WIDGET-RED", "mappedSkuId": 88012,
      "mrp": 1999.0, "offerPrice": 1499.0, "tp": 1100.0,
      "effectiveFrom": "2026-05-01T00:00:00", "effectiveTo": null,
      "inventory": [
        { "warehouseCode": "WH-MUM", "mappedWhId": 12, "qty": 40 },
        { "warehouseCode": "WH-DEL", "mappedWhId": 15, "qty": 12 }
      ],
      "totalQty": 52, "modifiedAt": "2026-06-02T07:45:00" }
  ],
  "page": 0, "pageSize": 50, "totalRecords": 1, "totalPages": 1, "hasNext": false
}

{
  "data": [
    { "supplierId": 7, "orderRef": "SO-100245", "mappedOrderId": null,
      "orderType": "ORDER_PUNCH", "orderStatus": "PROCESSING",
      "orderDate": "2026-06-03T11:20:00", "currency": "INR",
      "orderTotal": 2998.0, "totalItems": 2,
      "customer": { "firstName": "Sample", "lastName": "Buyer",
                    "email": "buyer@example.com", "phone": "+91-90000-00000" },
      "shippingAddress": { "name": "Sample Buyer", "company": null, "phone": "+91-90000-00000",
        "email": "buyer@example.com", "gst": null, "addr1": "12 Sample Street", "addr2": null,
        "city": "Mumbai", "state": "MH", "pincode": "400001", "country": "IN" },
      "billingAddress": { "name": "Sample Buyer", "company": null, "phone": "+91-90000-00000",
        "email": "buyer@example.com", "gst": null, "addr1": "12 Sample Street", "addr2": null,
        "city": "Mumbai", "state": "MH", "pincode": "400001", "country": "IN" },
      "items": [
        { "skuCode": "ACME-WIDGET-RED", "sellerSkuCode": "SLR-001", "mappedSkuId": 88012,
          "name": "Acme Widget (Red)", "qty": 2, "price": 1499.0, "subtotal": 2998.0,
          "lineStatus": "CONFIRMED" }
      ],
      "modifiedAt": "2026-06-03T11:21:10" }
  ],
  "page": 0, "pageSize": 50, "totalRecords": 1, "totalPages": 1, "hasNext": false
}

FAQ

Why is my dataset empty even though data exists?

The API only returns finalised master data (records that have completed internal validation/mapping). Records still in earlier processing stages are not exposed. If you expect data and see none, it may not yet be finalised.

My signature keeps failing (401 INVALID_SIGNATURE). What should I check?

Confirm: (1) the canonical string uses real newlines in the exact 6-line order; (2) you used the empty-body SHA-256 constant; (3) query parameters are percent-encoded and sorted identically to what you send; (4) X-Timestamp/X-Nonce in the string match the headers; (5) you are signing with the correct secret.

How fresh is the data?

Use modifiedAt as the source of truth for freshness and drive incremental syncs from it.

Can I call this from a browser?

No. Your secret must never be exposed to a browser or mobile app. Always call server-to-server.

Changelog