Quickstart

Onboarding path

1. Sign the robotics contract; Sitora registers you as a vendor.
2. Integrate against your Sitora-provided sandbox.
3. Pass the conformance suite — a passing run is recorded and attached to your certification. Sitora cannot certify a vendor without one.
4. Once certified, a restaurant owner requests your fleet for their filial from Sitora Biz; Sitora approves the activation; the owner mints your credential and (optionally) registers your webhook endpoint.

The sandbox

Sitora provisions each vendor a sandbox: a fully entitled test filial with your vendor registered, an active activation, a credential, and seeded orders already in the ready state — so offers exist the moment you connect. The sandbox behaves exactly like production: same API, same throttles, same error codes, same kill switches.

Your sandbox credential is delivered once, at provisioning. Store it; it is not retrievable again — a lost key means a rotation.

First requests

Poll for offers, claim one, and drive it to completion:

# 1. What is on offer?
curl -H "Authorization: Bearer sit_rk_..." \
  "https://<host>/api/robotics/v1/serving-tasks/?status=offered"

# 2. Claim it (first claim wins)
curl -X POST -H "Authorization: Bearer sit_rk_..." \
  -H "Idempotency-Key: claim-7f3a" \
  "https://<host>/api/robotics/v1/serving-tasks/42/claim/"

# 3. Wait for staff to load the tray (the task moves to `loaded`), then report
curl -X POST -H "Authorization: Bearer sit_rk_..." \
  -H "Idempotency-Key: report-7f3a-1" \
  -H "Content-Type: application/json" \
  -d '{"status": "en_route"}' \
  "https://<host>/api/robotics/v1/serving-tasks/42/report/"

Reports proceed en_route → arrived → completed; see serving tasks for the full lifecycle and polling and idempotency for the ETag and retry contract. Heartbeat every ~30 seconds throughout — a stale heartbeat silently stops offers.

The conformance suite

Certification is earned in your sandbox: the conformance suite drives the five scenarios below over the live API, and Sitora records the passing run as your certification artifact.

Scenario	What it proves
claim_before_expiry	You claim offers promptly and handle the claim race correctly.
idempotent_duplicate_reports	Duplicate reports with the same Idempotency-Key are replayed, not re-applied.
mid_route_failure_reporting	Failures are reported with a coded reason and the order falls back cleanly.
heartbeat_loss_and_recovery	A stale heartbeat stops offers; recovery is automatic on the next beat.
kill_switch_compliance	A paused or frozen filial refuses claims and your controller complies immediately.

All five scenarios must pass; the recorded run is what Sitora attaches to your vendor certification. Certification is re-run on breaking controller revisions you declare under contract.