Een levering aanmelden

Laat het magazijn weten wat een leverancier gaat brengen, en volg daarna hoe de goederen worden ontvangen.

Wanneer gebruik je dit

Gebruik dit recept als je inkoop in je eigen ERP loopt. Je ontvangstteam ziet de verwachte levering in Picked en scant de goederen daartegen binnen.

Je hebt nodig:

een token met het recht receipts:write (zie Authenticatie en rechten). Daarmee lees je een ontvangst ook terug;
het id van het magazijn waar de goederen heen gaan: GET /api/v1/warehouses geeft je magazijnen met hun warehouse_id (zie Aan de slag).

Meld de levering aan

POST /api/v1/receipts neemt één levering aan. Elke regel noemt een product dat Picked al kent, met sku of met product_id, niet allebei. Noem de leverancier als tekst met supplier, of met supplier_id voor een leverancier die je in Picked hebt aangemaakt.

curl -X POST "https://picked.nl/api/v1/receipts" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse_id": 12,
    "reference": "INK-2026-0457",
    "supplier": "Fietsgroothandel Rijnmond BV",
    "expected_at": "2026-10-14",
    "lines": [
      { "sku": "BEL-ZW-01", "quantity_expected": 48 },
      { "sku": "BAND-28-622", "quantity_expected": 120 }
    ]
  }'

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/receipts/731

{
  "id": 731,
  "reference": "INK-2026-0457",
  "status": "expected",
  "warehouse_id": 12,
  "supplier": "Fietsgroothandel Rijnmond BV",
  "expected_at": "2026-10-14",
  "expected_total": 168,
  "received_total": 0,
  "lines": [
    { "product_id": 2210, "sku": "BEL-ZW-01", "quantity_expected": 48, "quantity_received": 0 },
    { "product_id": 9134, "sku": "BAND-28-622", "quantity_expected": 120, "quantity_received": 0 }
  ],
  "created_at": "2026-10-10T09:14:03+02:00",
  "_links": {
    "self": { "href": "/api/v1/receipts/731" }
  }
}

Een levering heeft 1 tot 500 regels. Zonder expected_at verwacht Picked hem op de dag dat je hem aanmeldt.

Stuur altijd een reference mee, zoals je inkoopordernummer. Meld je dezelfde reference opnieuw aan, dan krijg je de ontvangst van de eerste aanroep terug met 200 OK, dus een nieuwe poging meldt een levering nooit dubbel aan. Zonder reference is elke aanroep een nieuwe levering. Idempotentie legt het precies uit.

Volg de ontvangst

Lees de ontvangst terug met het id uit het antwoord:

curl "https://picked.nl/api/v1/receipts/731" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 731,
  "reference": "INK-2026-0457",
  "status": "receiving",
  "warehouse_id": 12,
  "supplier": "Fietsgroothandel Rijnmond BV",
  "expected_at": "2026-10-14",
  "expected_total": 168,
  "received_total": 48,
  "lines": [
    { "product_id": 2210, "sku": "BEL-ZW-01", "quantity_expected": 48, "quantity_received": 48 },
    { "product_id": 9134, "sku": "BAND-28-622", "quantity_expected": 120, "quantity_received": 0 }
  ],
  "created_at": "2026-10-10T09:14:03+02:00",
  "_links": {
    "self": { "href": "/api/v1/receipts/731" }
  }
}

status gaat alleen vooruit: expected → receiving zodra de eerste regel binnen is → received als alle regels compleet zijn → completed als het magazijn de ontvangst afsluit. Het magazijn kan een ontvangst ook afsluiten terwijl hij nog receiving is, dus completed betekent niet dat alles binnen is. En tot hij is afgesloten, kan het magazijn hem annuleren (cancelled). Vergelijk per regel quantity_received met quantity_expected om te zien wat er nog ontbreekt.

Picked laat niet uit zichzelf weten dat een ontvangst verandert. Lees hem dus af en toe terug, bijvoorbeeld een paar keer per dag zolang hij openstaat, en stop zodra hij completed of cancelled is.

Fouten afhandelen

Status	Wat je doet
`422` `validation_failed`	Verbeter het verzoek: `errors` noemt elk veld. Een SKU die Picked niet kent, wordt hier geweigerd, anders dan bij orders. Voeg het product dus eerst toe.
`404` `not_found`	Bij teruglezen: geen ontvangst met dat id in je werkruimte.
`403` `missing_ability`	Het token mist het recht `receipts:write`.
`503` of een andere `5xx`	Stuur hetzelfde verzoek na een pauze opnieuw. Door de `reference` meld je niets dubbel aan.

Foutmeldingen noemt alle codes, en Rate limits wat je doet bij een 429.

Probeer het met een proefrun

Zet de header Picked-Dry-Run: true erbij om een aanmelding te controleren zonder iets te schrijven:

curl -X POST "https://picked.nl/api/v1/receipts" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Picked-Dry-Run: true" \
  -d '{
    "warehouse_id": 12,
    "reference": "INK-2026-0458",
    "supplier": "Fietsgroothandel Rijnmond BV",
    "lines": [
      { "sku": "BEL-ZW-01", "quantity_expected": 24 }
    ]
  }'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": null,
  "reference": "INK-2026-0458",
  "status": "expected",
  "warehouse_id": 12,
  "supplier": "Fietsgroothandel Rijnmond BV",
  "expected_at": "2026-10-13",
  "expected_total": 24,
  "received_total": 0,
  "lines": [
    { "product_id": 2210, "sku": "BEL-ZW-01", "quantity_expected": 24, "quantity_received": 0 }
  ],
  "created_at": null,
  "dry_run": true,
  "would": "created"
}

In Proefruns lees je wat een proefrun controleert.