API Reference

The connector talks to three endpoints. All are under the API base https://hkjshopping-production.up.railway.app/api and authenticate with the X-API-Key header.

Method	Path	Purpose
POST	/integration/events	Ingest one canonical event or a batch.
POST	/integration/bulk	Upload a JSON/CSV/XML catalog for async import.
GET	/integration/bulk/{batch_id}	Poll a bulk import's progress.

Payload shapes are defined in the Canonical Contract. Credentials are issued by the shop owner — see Credentials.

---

POST /integration/events

Ingest one canonical event, or a JSON array of events (a batch). Events are idempotent on event_id and processed independently — one bad event never fails the rest.

Headers

Header	Required	Value
X-API-Key	✓	Your integration key (ik_live_…).
Content-Type	✓	application/json

Body — a single event envelope or an array of them.

Response 200 — a per-event result list plus a roll-up summary:

{
  "results": [
    { "event_id": "e1", "status": "applied", "action": "product.upserted", "product_id": 812 }
  ],
  "summary": { "received": 1, "applied": 1, "skipped": 0, "duplicate": 0, "error": 0 }
}

Each result carries the event_id (when known) and a status:

status	extra fields	meaning
applied	action, product_id or order_id	processed and persisted
skipped	action, reason	no-op — e.g. stock for an unknown product
duplicate	—	this event_id was already processed
error	error	validation failed; the product/order is unchanged

Note

The HTTP status is 200 even when individual events are skipped or error — inspect the per-event status. A malformed envelope with no readable event_id returns an error result without an event_id.

Other responses

Code	When
400	Body is not valid JSON.
401	Missing or unknown X-API-Key.
403	The integration is disabled.

---

POST /integration/bulk

Upload a catalog file for asynchronous import. The file is parsed immediately (so format errors return right away), then processed in the background.

Headers — X-API-Key (required).

Query / form

Param	In	Notes
format	query	json (default), csv, or xml. Falls back to the shop's configured default.
file	multipart form	The catalog file. Alternatively, send the file as the raw request body.

Response 202

{ "batch_id": 42, "status": "pending", "total_rows": 1200 }

total_rows is the number of products after parsing (CSV forward-fill rows are already merged). Poll the batch to follow progress.

Other responses

Code	When
400	Empty upload, or the file can't be parsed for the declared format.
401 / 403	As above.

---

GET /integration/bulk/{batch_id}

Poll a bulk import. Scoped to your shop — another shop's batch returns 404.

Headers — X-API-Key (required).

Response 200

{
  "batch_id": 42,
  "format": "csv",
  "status": "done",
  "total_rows": 1200,
  "processed_rows": 1198,
  "error_rows": 2,
  "error_kind": null,
  "error_summary": "1198 of 1200 rows imported; 2 skipped — see the errors below.",
  "retriable": false,
  "errors": [
    { "row": 17, "error": "'title_ar' is required and must be a non-empty string." }
  ]
}

status moves pending → started → done (or failed). A few bad rows still yield done — the good rows import and errors lists the failures (capped at the first 200). On failed, error_kind is invalid_data (fix the file and re-upload) or system (retriable: true).

Other responses

Code	When
401 / 403	As above.
404	No such batch for your integration.

---

Outbound calls (HKJ → you)

These aren't endpoints you call — they're requests we send to the outbound_url you registered. See §4 for payloads and Outbound authenticity for signature verification.