Integration Documentation
A versioned API surface for organisation integrations to ingest masters and
transactions into Nexxio, manage EC sales data (contacts, leads, salesmen), push sales invoices, outstandings, ledger transactions (credit notes, payments, receipts), and stock-on-hand balances, and pull sales invoices, outstandings, ledger transactions, sales orders, and quotations.
All data endpoints live under /v1/public-api and authenticate with an
organisation API key (x-api-key).
How to connect
Three steps to go live:
- Register your organisation with Nexxio and request public API access.
- Receive an
x-api-keywith the scopes appropriate to your integration (for exampleproducts:write,categories:read,dealers:write,contacts:read,leads:write,salesmen:read,sales_invoices:write,sales_invoices:read,outstandings:write,outstandings:read,ledger_transactions:write,ledger_transactions:read,stock:write,orders:read,quotations:read). - Use the staging base URL for development and integration testing (see Live API testing below).
Base URLs
| Environment | Base URL | Notes |
|---|---|---|
| Staging (Dev) | https://api.integration-service.appnow.in | Use for integration testing and the public playground. |
| Production | Provided at go-live | Not available in the public playground — contact Nexxio support when you are ready for production. |
The staging host is the default for all examples and live try-it requests on this page. Production credentials and URLs are issued during onboarding for go-live only.
Authentication
Every request must carry the x-api-key header with your API key string — not the server base URL.
x-api-key: your-api-key-from-onboarding
| Header | Required | Purpose |
|---|---|---|
x-api-key | Required | Organisation API key issued by Nexxio. |
Idempotency-Key | Required for writes | UUID per logical batch. Replays return the original outcome. |
Content-Type | Required with body | application/json for POST/PUT payloads. |
Integration takeaways
| Topic | Required integration behaviour |
|---|---|
| Base endpoint | Call /v1/public-api/* on integration-service URLs only. |
| Auth header | Send x-api-key on every request. Never send bearer auth for this API. |
| Write safety | Send Idempotency-Key for write requests (POST/PUT/PATCH/DELETE) to prevent duplicate processing. |
| Body format | Set Content-Type: application/json whenever a request body is present. |
| Operational flow | Treat write responses as async acknowledgements and poll the jobs endpoint until completion. |
Conventions
Async by default
Write endpoints accept the payload, return HTTP 200 with { job_id, status: "accepted" } in response, and process records in the background. Poll GET /v1/public-api/jobs/<jobId> for completion.
Batch sizes
Each write endpoint accepts a single object or an array under items. Default soft limit is 50 records per request. Contact Nexxio support if you need a higher limit.
Idempotency semantics
- Same
Idempotency-Key+ identical body within the TTL replays the original response. - Same key with a different body fingerprint returns
409 IDEMPOTENCY_CONFLICT. - Default TTL is 24 hours.
Identifiers
Nexxio uses stable external identifiers on the public API (for example category_code, sku_factory_id, dealer code).
Error model
Errors use the same envelope as success responses:
{
"error_status": true,
"error": { "code": 500, "message": "Internal server error" },
"message": "Invalid or expired API key"
}
Common cases:
| message (typical) | When |
|---|---|
Missing x-api-key header | Header not sent. |
Invalid x-api-key: use your API key here, not a base URL | A URL was sent in x-api-key by mistake. |
Invalid or expired API key | Unknown or inactive key. |
Insufficient scope | Key lacks the scope required by the endpoint. |
Idempotency-Key header is required | Write without idempotency header. |