POS integration

The integration is two one-way channels sharing one credential. The restaurant issues an API key from Dashboard → Settings → Integrations, and registers your webhook receiver there too.

Start from the edges: register a webhook and confirm you receive order.created, then add the status PATCH. Base URL: https://api.sahtein.app/v1 (self-hosted installations use their own host).

Every API call carries the key in an Authorization header:

Authorization: Bearer shk_<12-char prefix>_<48-char secret>

The full token is shown once, at creation — we store only a hash. A key carries scopes chosen at creation (orders:read, orders:write, menu:read, menu:write); calls outside them return 403. Keys are server-to-server only — never ship one in a browser or a mobile app. If a key leaks, revoke it in the dashboard; revocation is immediate.

Every error is JSON with a stable code:

{
  "error": {
    "code": "invalid_transition",
    "message": "Invalid transition: ready → accepted",
    "requestId": "..."
  }
}

When something happens we POST JSON to your URL. Respond 2xx within 8 seconds; anything else is retried on the schedule below. Heavy processing belongs on your own queue — acknowledge first, work later.

Envelope and headers

POST <your-url>
Content-Type: application/json
X-Sahtein-Event: order.created
X-Sahtein-Delivery: <uuid — use as your dedup key>
X-Sahtein-Signature: t=<unix seconds>,v1=<hex hmac>

{
  "id": "<delivery uuid>",
  "event": "order.created",
  "created_at": "2026-08-18T10:30:45.123Z",
  "tenant_id": "<restaurant uuid>",
  "data": { ...event-specific payload... }
}

Verifying the signature

The signature is HMAC-SHA256 over `${t}.${rawBody}` with the endpoint secret shown when the endpoint was registered. Verify against the raw request body, before any JSON parsing:

const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(parts.v1)
  );
}

Reject unverified payloads with 401 and do not process them. Retries mint a new delivery id per attempt, so dedup on X-Sahtein-Delivery and you will never double-process.

Events

Money fields are integer agorot (₪108.50 = 10850). Item and product names are localized objects ({"ar": "...", "he": "...", "en": "..."}) — pick the language your screen prints.

Retry schedule

After six failures the delivery is marked abandoned. Nothing is deleted — the restaurant sees the full history in the dashboard and can retry an abandoned delivery manually. Webhooks are emitted transactionally with the change they describe: if you receive an event, a GET for that order will always succeed.

GET  /partner/v1/orders?status=active&page=1&per_page=30
GET  /partner/v1/orders/{id}
PATCH /partner/v1/orders/{id}/status   { "status": "in_preparation" }

status=active returns everything in flight. The PATCH drives the same state machine as the restaurant's own console and kitchen screen — your update moves the customer's live tracking page, prints tickets, and the console in one stroke. Setting accepted performs full acceptance: kitchen tickets are routed and print jobs queued exactly as if staff had tapped Accept.

Cancellation and refunds are staff-only (they touch money) and return 409 from this API. Illegal moves — e.g. delivered straight from accepted — return 409 invalid_transition.

Loop warning: your own PATCH triggers an order.status_changed webhook back at you. Dedup on the delivery id and never react to a transition you caused.

GET   /partner/v1/branches
GET   /partner/v1/menu
PATCH /partner/v1/menu/items/{productId}/availability   { "available": false }

The menu read returns sections with items, prices (agorot) and availability. The availability PATCH is the sold-out push: flipping available: false hides the item from the website, app, kiosk and table QR at the same moment, and emits menu.availability_changed to every subscriber (including you — see the loop warning above).

600 requests/minute per key, plus a burst shield of 40 requests/second. Both are far above what a synchronized POS needs — approaching either usually means an event loop reacting to itself. Over a limit you get 429 with Retry-After; successful partner responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset for the per-minute budget.

1. Get an API key from the restaurant (Settings → Integrations); store it in a vault, never in client code.
2. Smoke-test with GET /partner/v1/orders?per_page=1.
3. Register your webhook endpoint; verify the HMAC against the raw body; dedup on X-Sahtein-Delivery.
4. Acknowledge within 8 seconds; queue heavy work on your side.
5. PATCH /orders/{id}/status at each kitchen step; ignore the webhook echoes of your own transitions.
6. Optional: pull /menu daily and push sold-out flags as stock runs out.

Questions: [email protected] — include the X-Sahtein-Delivery id or order_id you're asking about.