Een procesrun starten vanuit een ander systeem

Laat je systeem werk op de vloer zetten: je ERP vraagt om locatie A-03-2 te tellen, een leveranciersportaal meldt een levering die een ontvangstrun nodig heeft, of een planningstool wil nu een batch laten picken. Je systeem start een run van een proces, en de eerste medewerker die hem op de vloer oppakt, werkt hem af.

Wanneer gebruik je dit

Gebruik dit recept als het werk ergens vandaan komt waar Picked het niet plant. Een run die je zo start, is dezelfde als een run die een planning opent: hij wacht, aan niemand toegewezen, tot een medewerker hem oppakt.

Je hebt een token nodig met het recht process-runs:write (zie Authenticatie).

Zoek het proces op

Een proces heeft een publieke id, een UUID. Open in Picked Processen en dan de instellingen van het proces: daar staat zijn API-id, met een knop om hem te kopiëren. Het proces moet gepubliceerd en ingeschakeld zijn. Een concept dat nooit gepubliceerd is, kun je niet starten, en een proces dat alleen als stap van een ander proces draait ook niet.

De variabelen die een proces declareert, zijn waarmee een run kan starten. Markeert het proces een variabele als verplicht, dan wordt een run die zonder die variabele gestart wordt geweigerd.

Start de run

POST /api/v1/processes/{process}/runs met het magazijn waarin de run wordt gewerkt en de variables waarmee hij start. Alleen variabelen die het proces declareert worden aangenomen, elk van het gedeclareerde type: een tekst, een getal, true of false, een object of een lijst. De rest start met de standaardwaarde, en null laat een variabele die niet verplicht is op zijn standaardwaarde.

Stuur een Idempotency-Key-header mee, een tekst die uniek is voor dit verzoek, zoals je eigen opdrachtnummer. Geeft de aanroep een time-out en stuur je hem opnieuw met dezelfde sleutel, dan krijg je het eerste antwoord terug en opent er geen tweede run.

curl -X POST "https://picked.nl/api/v1/processes/0192f5a0-7c1e-7b3a-9d4e-2f6a8b1c3d5e/runs" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-count-48211" \
  -d '{
    "warehouse_id": 12,
    "variables": { "location": "A-03-2", "expected_quantity": 40 }
  }'

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/process-runs/5512

{
  "id": 5512,
  "process": "0192f5a0-7c1e-7b3a-9d4e-2f6a8b1c3d5e",
  "warehouse_id": 12,
  "status": "pending",
  "variables": { "location": "A-03-2", "expected_quantity": 40 },
  "created_at": "2026-10-14T09:12:44.000000Z",
  "started_at": null,
  "completed_at": null,
  "opened": true,
  "_links": {
    "self": { "href": "/api/v1/process-runs/5512" }
  }
}

Eén run per ding

Een herhaling is één ding; twee keer om hetzelfde werk vragen is iets anders. Kan je systeem opnieuw vragen om A-03-2 te tellen terwijl de eerste telling nog openstaat, stuur dan dedupe_on mee met de naam van een tekstvariabele. Staat er nog een run van het proces open met dezelfde waarde, dan antwoordt Picked 200 met die run en opened: false, en opent het niets. Is die run klaar, dan opent het volgende verzoek een nieuwe.

{
    "warehouse_id": 12,
    "variables": { "location": "A-03-2" },
    "dedupe_on": "location"
}

Lees de run terug

GET /api/v1/process-runs/{id} geeft de run zoals hij nu is: pending tot een medewerker hem oppakt, dan in_progress, en completed als het werk klaar is. Zijn variables zijn die waarmee de run startte, met de standaardwaarden erbij.

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

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

{
  "id": 5512,
  "process": "0192f5a0-7c1e-7b3a-9d4e-2f6a8b1c3d5e",
  "warehouse_id": 12,
  "status": "pending",
  "variables": { "location": "A-03-2", "expected_quantity": 40 },
  "created_at": "2026-10-14T09:12:44.000000Z",
  "started_at": null,
  "completed_at": null,
  "_links": {
    "self": { "href": "/api/v1/process-runs/5512" }
  }
}

Fouten om af te handelen

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

Testen

Stuur de aanroep met een Picked-Dry-Run: true-header. Hij wordt gecontroleerd tegen je echte processen en magazijnen en antwoordt 200 met de run die hij zou openen, id leeg en would: created, en er opent niets. Zie Proefruns.