HKJ Integration¶

Connect your commerce system — Magento, Shopify, WooCommerce, or anything else — to HKJ through one provider-agnostic contract. You translate your system's data to and from the canonical shapes; HKJ never needs to know your internals, and you never need to know ours.

Canonical Contract The events, payloads, and rules — inbound (catalog/stock/price) and outbound (orders).
API Reference The three connector endpoints — requests, responses, and status codes.

The big picture¶

You build one small connector that speaks our contract. Everything flows through it — your catalog comes in, and the orders our chatbot places go out to you to fulfill.

flowchart LR
    sys[("Your system:<br/>catalog & orders")]
    conn["Your connector<br/>(your format ⇄ our contract)"]
    hkj["HKJ"]
    bot(["Shopper ↔ chatbot"])

    sys <--> conn
    conn -- "catalog · stock · prices" --> hkj
    hkj -- "order placed (signed webhook)" --> conn
    conn -- "order status updates" --> hkj
    hkj --- bot

You → HKJ: keep the catalog, stock, and prices in sync; report order status as you fulfill.
HKJ → you: the orders the chatbot places, pushed to you signed and ready to fulfill.

The two sides never learn each other's internals — the contract in the middle is the only thing you implement.

Quickstart¶

Get credentials. The shop owner provisions your integration in the HKJ dashboard and gives you an API key (ik_live_…) and a signing secret. The key is shown once.

Push your catalog. Either stream live updates or upload a file:

Streaming eventBulk file

curl -X POST https://hkjshopping-production.up.railway.app/api/integration/events \
  -H "X-API-Key: ik_live_xxx" -H "Content-Type: application/json" \
  -d '{
        "event_id": "evt-1",
        "event_type": "product.upserted",
        "data": { "sku": "HNY-500", "title_en": "Honey", "title_ar": "عسل",
                  "price_fils": 5000, "stock_qty": 12 }
      }'

curl -X POST "https://hkjshopping-production.up.railway.app/api/integration/bulk?format=csv" \
  -H "X-API-Key: ik_live_xxx" -F "file=@catalog.csv"
# → { "batch_id": 42, "status": "pending", "total_rows": 1200 }

Receive orders. HKJ POSTs order.placed to your registered URL, signed with X-Signature. Verify the signature, create the order, and reply with your order id.
Report status. As you fulfill, send order.status_changed back so the shopper can track the order in chat.

See the Canonical Contract for the full event catalogue and field-level details.

Base URL

Replace https://hkjshopping-production.up.railway.app with your HKJ API base URL throughout these docs.