Rychlý start

1. Vytvořte sandboxový klíč

V tenant administraci otevřete Integrace, vytvořte testovací API klíč a ihned jej bezpečně uložte. Celý klíč se zobrazí pouze jednou.

export EASYPICK_API_KEY='ep_test_PUBLIC_ID_SECRET'
export EASYPICK_API_URL='https://sandbox-api.easypick.cz/v1'

2. Vyberte box

curl --fail-with-body \
  --header "Authorization: Bearer $EASYPICK_API_KEY" \
  "$EASYPICK_API_URL/boxes"

Odpověď obsahuje pouze aktivní boxy vašeho klienta:

{
  "items": [
    {
      "id": "box_01k3example",
      "name": "Box Praha 1",
      "location_name": "U hlavního vchodu",
      "address": "Dlouhá 1, Praha"
    }
  ]
}

3. Rezervujte schránku

external_order_id je současně idempotency key. Při opakování stejného requestu pro stejný box vrátí EasyPick původní zásilku a stejný PIN.

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $EASYPICK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "box_id": "box_01k3example",
    "external_order_id": "ORDER-2026-1042",
    "customer_name": "Jan Novák"
  }' \
  "$EASYPICK_API_URL/shipments"

Nová rezervace vrátí HTTP 201:

{
  "id": "shipment_01k3example",
  "external_order_id": "ORDER-2026-1042",
  "attempt_number": 1,
  "retry_of_shipment_id": null,
  "box_id": "box_01k3example",
  "compartment_code": "A2",
  "customer_name": "Jan Novák",
  "status": "reserved",
  "compartment_state": "reserved",
  "pickup_enabled": false,
  "reservation_expires_at": "2026-08-03T10:00:00Z",
  "loaded_at": null,
  "pickup_available_at": null,
  "pickup_expires_at": null,
  "picked_up_at": null,
  "updated_at": "2026-08-02T10:00:00Z",
  "pickup_pin": "418205"
}

4. Simulujte naskladnění

Sandbox umožňuje deterministicky posouvat stav bez fyzického boxu:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $EASYPICK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"event":"loaded"}' \
  "$EASYPICK_API_URL/sandbox/shipments/shipment_01k3example/events"

Následně použijte události picked_up a door_available. Podrobný seznam přechodů je v kapitole Sandbox.

PHP 8.2+

<?php
$response = file_get_contents(
    getenv('EASYPICK_API_URL') . '/boxes',
    false,
    stream_context_create(['http' => ['header' => [
        'Authorization: Bearer ' . getenv('EASYPICK_API_KEY'),
        'Accept: application/json',
    ]]])
);
$boxes = json_decode($response, true, flags: JSON_THROW_ON_ERROR);

Node.js 20+

const response = await fetch(`${process.env.EASYPICK_API_URL}/boxes`, {
  headers: { Authorization: `Bearer ${process.env.EASYPICK_API_KEY}` },
});
if (!response.ok) throw new Error(await response.text());
const { items: boxes } = await response.json();