Zásilky a stavy

EasyPick sleduje odděleně stav zásilky a fyzický stav schránky. Webhook je událost, která oznamuje změnu; nemusí sám měnit stav zásilky.

Stav zásilky

reserved -> loaded -> picked_up
    |          |
    +----------+-> cancelled / expired / fault

Stav	Význam
reserved	Schránka je rezervovaná, ale zásilka ještě není potvrzeně naskladněná.
loaded	Zásilka je ve schránce. Řiďte se také hodnotou pickup_enabled.
picked_up	Zákazník zásilku vyzvedl. Schránka ještě může být v cooldownu.
cancelled	Zásilka byla zrušena. Pokud už byla naskladněná, čeká schránka na fyzické odebrání.
expired	Vypršela rezervace nebo lhůta pro vyzvednutí. Naskladněný obsah se musí fyzicky odebrat.
fault	Terminální stav zásilky po operaci, kterou nebylo možné bezpečně dokončit.

cancelled, expired a fault jsou terminální stavy. Fyzické odebrání obsahu je už nezmění na jiný stav zásilky.

Fyzický stav schránky

Veřejné odpovědi GET /shipments/{shipment_id} a webhookové payloady obsahují pole compartment_state.

compartment_state	Význam
reserved	Schránka je vyhrazená pro zásilku, ale naskladnění ještě nebylo potvrzeno.
occupied	Schránka fyzicky obsahuje zásilku.
awaiting_removal	Zásilka je terminální, ale obsah musí obsluha fyzicky odebrat.
cooldown	Vyzvednutí je potvrzené, schránka však ještě čeká na provozní uvolnění.
available	Schránka je skutečně volná a lze ji rezervovat pro další zásilku.

vytvoření zásilky:          available -> reserved
naskladnění:                reserved -> occupied
prázdná rezervace:          reserved --door_available--> available
terminální stav po naložení: occupied -> awaiting_removal
fyzické odebrání:           awaiting_removal --removed + door_available--> available
vyzvednutí:                 occupied -> cooldown --door_available--> available

Událost removed potvrzuje fyzické odebrání obsahu ze schránky ve stavu awaiting_removal. Následující door_available potvrzuje její skutečné uvolnění. Ani jedna z těchto událostí nemění terminální stav zásilky.

Ochranná lhůta

Po prvním naskladnění je stav hned loaded, ale pickup_enabled zůstává dočasně false. Zásobovatel může stejným PINem schránku znovu otevřít a opravit obsah. Zákazníkovi posílejte PIN až po webhooku loaded, který EasyPick odloží do konce ochranné lhůty a do potvrzeného zavření dveří.

Vytvoření

POST /shipments
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "box_id": "box_01k3example",
  "external_order_id": "ORDER-2026-1042",
  "customer_name": "Jan Novák",
  "reservation_ttl_minutes": 1440,
  "pickup_ttl_minutes": 4320
}

TTL pole jsou volitelná. Bez nich se použije nastavení konkrétního boxu.

Načtení stavu

GET /shipments/{shipment_id}

Odpověď obsahuje vedle status také compartment_state. Stav zásilky proto nepoužívejte jako jediný signál, že lze schránku znovu rezervovat. Status endpoint PIN nevrací. Pro auditované opětovné načtení použijte GET /shipments/{shipment_id}/pickup-pin.

Zrušení

POST /shipments/{shipment_id}/cancel

Zrušit lze rezervovanou nebo naskladněnou zásilku. Opakované zrušení je idempotentní.

• Prázdná rezervace přejde rovnou na compartment_state=available a EasyPick odešle door_available.
• Naskladněná zásilka přejde na status=cancelled, ale schránka zůstane compartment_state=awaiting_removal. Obsluha musí obsah fyzicky odebrat; teprve události removed a door_available potvrdí uvolnění.

Obnova po fault

fault je terminální stav zásilky, nikoliv automatické uvolnění schránky. Standardní bezpečný postup je:

1. Obsluha zvolí otevření pro odebrání.
2. Box potvrdí cyklus čidla closed -> open -> closed.
3. Obsluha potvrdí, že je schránka prázdná.
4. EasyPick odešle removed a poté door_available; zásilka zůstane ve stavu fault a schránka přejde na available.

Nouzové uvolnění použijte pouze po fyzické kontrole prázdné schránky. Přeskočení kontroly může způsobit přidělení schránky, ve které zůstal obsah.

Opakování zásilky po chybě

POST /shipments/{shipment_id}/retry
Authorization: Bearer {api_key}

Endpoint lze použít pouze pro zásilku ve stavu fault, jejíž původní schránka už byla skutečně uvolněna (compartment_state=available). Vytvoří nový pokus se stejným external_order_id, rezervuje aktuálně dostupnou schránku a vygeneruje nový PIN. Původní zásilka zůstává ve stavu fault kvůli auditu.

Operace je idempotentní vůči ID původního chybového pokusu. Opakované volání vrátí stejný nový pokus a stejný nový PIN; nevytvoří další rezervace.

Původní POST /shipments zůstává idempotentní vůči prvnímu požadavku: jeho opakování se stejným external_order_id vrátí první pokus. Pro opakování po chybě vždy použijte /retry a uložte si ID vráceného nového pokusu.

Kdy je schránka znovu volná

Jediným veřejným stavem potvrzujícím možnost další rezervace je compartment_state=available. Webhook door_available je kanonická událost po každém skutečném uvolnění schránky:

• po skončení cooldownu běžného vyzvednutí,
• po removed u naskladněné zásilky ve stavu cancelled, expired nebo fault,
• po okamžitém uvolnění nenaskladněné rezervace.

door_available stav zásilky nemění.