Heartbeat and fleet state

Heartbeat

POST /fleet/heartbeat/ every ~30 seconds while your fleet is on duty. The body accepts an optional summary object (robot counts, battery state — whatever your operations find useful); it is stored for diagnostics.

If your last heartbeat is older than the filial’s staleness window (heartbeat_stale_seconds in the snapshot), the fleet is offline: offers stop silently and staff serve as usual. Recovery is automatic on the next heartbeat — no re-registration, no escalation.

The fleet snapshot

Both GET /fleet/ and the heartbeat response return the same snapshot:

Field	Meaning
filial_id	The branch this credential is scoped to.
activation_status	The activation’s lifecycle state.
confirmation_policy	human_confirmed or auto_confirm.
auto_confirm_dwell_seconds	Minimum gap between arrived and completed under auto-confirm.
offer_expiry_seconds	How long an offer stays claimable.
heartbeat_stale_seconds	The staleness window for fleet liveness.
fleet_online	Whether your heartbeat is currently fresh.
offers_enabled	Whether new offers can currently reach you.
blocked_reasons	Why offers are stopped, when they are (see below).
server_time	Authoritative clock — use it to schedule dwell-sensitive reports.

blocked_reasons

When offers_enabled is false, blocked_reasons names every reason currently in force:

Code	Meaning
platform_frozen	Sitora engaged the platform-wide freeze.
no_activation	The filial has no robotics activation.
vendor_not_certified	The vendor’s certification is not currently valid.
entitlement_missing	The restaurant’s plan does not include robotics.
robotics_paused	The owner, a branch manager, or Sitora paused this filial.
activation_not_active	The activation exists but is not in an active state.
fleet_offline	Your heartbeat is stale.

Treat these as diagnostics, not failures: keep heartbeating, park your robots, and wait. Every blocked state except fleet_offline is resolved on the Sitora side; fleet_offline is resolved by your own next heartbeat.