Documentation

A REST surface for approved partners to ingest masters, transactions, and stock into Nexxio and to receive event-driven webhooks. All endpoints are versioned under /v1/public-api and authenticated with a perexternal API key.

Partners must complete onboarding with the Nexxio team to receive an x-api-key credential, scopes, and IP allow-list configuration before calling production endpoints.

How to connect

Three steps to go live:

Register your company in the Nexxio dashboard and request public-API access.
Receive an x-api-key with the scopes appropriate to your integration (for example products:write, categories:read, dealers:write).
Use the staging base URL during integration; switch to production after sign-off.

Base URLs

Environment	Base URL
Production	`https://rest.nexxio.app`
Staging	`https://rest-staging.appnow.in`

Replace the example hostnames above with the values issued during onboarding.

Authentication

Every request must carry the x-api-key header. The key resolves to a single account (client_id) and a fixed set of scopes.

x-api-key: nxa_live_8f3c1d2a9b...your-key-here...

Header	Required	Purpose
`x-api-key`	Required	Resolves `client_id` and scopes. Treat as a secret.
`Idempotency-Key`	Required for writes	UUID per logical batch. Replays return the original outcome.
`X-Request-Id`	Optional	Echoed in the response and persisted for audit.

Do not include client_id in payloads. The server derives it from the API key and rejects requests that try to override it.

Conventions

Async by default

Write endpoints accept the payload, return 202 Accepted with a job_id, and process records in the background. Poll GET /v1/public-api/jobs/<jobId> for status and per-record errors.

Batch sizes

Each write endpoint accepts a single object or an array under items. Default soft limit is 50 records per request, tunable during onboarding.

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 never exposes internal database ids on the public API. All references use stable, perexternal identifiers (for example category_code, sku_factory_id, dealer code).

Error model

All errors share a single envelope:

{
  "request_id": "1c3b4d2e-7f49-4d9d-9b3e-3c0bdfb43d3f",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Payload failed validation",
    "details": [
      { "index": 3, "field": "sku.gst_rate", "issue": "must be a number" }
    ]
  }
}

HTTP	error.code	When
400	`VALIDATION_FAILED`	Bad payload shape, missing required fields, server-managed fields present.
400	`IDEMPOTENCY_KEY_REQUIRED`	Header missing on a write.
401	`UNAUTHORIZED`	Missing, expired, or unknown API key.
403	`SCOPE_DENIED`	Key lacks the scope required by the endpoint.
404	`NOT_FOUND`	Entity (for example a job id) not found for this account.
409	`IDEMPOTENCY_CONFLICT`	Same key with different body.
429	`RATE_LIMITED`	External or per-resource limit exceeded.
500	`INTERNAL`	Unhandled server error.