Kwaliteitscontrole-integratie

Integreer een extern QA- / labsysteem met Roasthubs via QC-webhooks en legacy /api/-reads.

Lot-id_tag-waarden worden gegenereerd als {eerste 3 letters van zonenaam}-{sequence} (bijv. green → GRE-4, roast → ROA-12).

Flow

Parameter recorded on lot
 │
 ▼
 Target evaluated ──► lot_target_pass | lot_target_fail
 │
 ▼ (all targets evaluated)
 Overall QC ────────► lot_qc_pass | lot_qc_fail
 │
 ▼
 Webhook POST → GET /api/lots/:id + GET /api/lots_targets?lot_id=:id

Abonneer u op de vier QC-events onder System → Webhooks.
Bij delivery gebruikt u resource_id als lot-id (bevestig met data.lot_id wanneer aanwezig).
Laad lot- / QC-detail met de /api/-calls hieronder (geen QC-lot-GET op v2 vandaag).
Dedupliceer op webhook-id; geef snel 2xx terug.

Webhook-envelope

POST JSON, retries met exponentiële backoff. id is de idempotency-sleutel.

{
 "id": 18402,
 "type_id": "lot_qc_fail",
 "user_id": 4,
 "resource_id": 4,
 "roasthubs_zone_id": 1,
 "data": {}
}

Veld	Betekenis
`id`	Event-id (dedupe)
`type_id`	Eventnaam hieronder
`resource_id`	Lot-id voor follow-up-GET's
`roasthubs_zone_id`	Zone van het lot
`data`	Eventpayload

QC-events

`lot_target_pass` / `lot_target_fail`

Wordt afgevuurd wanneer één target op een lot wordt geëvalueerd (na POST/PUT /api/lots_parameters, of boolean approve).

data is de bijgewerkte lots_targets-rij:

{
 "id": 101,
 "lot_id": 4,
 "target_id": 7,
 "target_name": "Moisture",
 "parameter_id": 3,
 "parameter_name": "Moisture",
 "lower_bound": 10,
 "upper_bound": 12.5,
 "boolean_target": null,
 "status": "fail",
 "value": null,
 "last_evaluated": "2026-09-03T10:15:02.441Z",
 "created_at": "2026-09-01T08:05:11.102Z"
}

Gebruik "pass" of "fail" in status afhankelijk van het event.

Boolean bulk-approve kan in plaats daarvan sturen:

{ "status": "pass", "target_id": 101 }

In dat pad kan resource_id de target-id zijn — geef de voorkeur aan data.lot_id / een follow-up GET /api/lots_targets bij twijfel.

`lot_qc_pass` / `lot_qc_fail`

Wordt afgevuurd wanneer elk target op het lot is geëvalueerd. Fail als enig target faalde (status → qc_failed).

data is het lot inclusief lots_targets:

{
 "id": 4,
 "id_tag": "GRE-4",
 "number": "BL-2401",
 "recipe_id": 10,
 "roasthubs_zone_id": 1,
 "status": "qc_failed",
 "datetime_qc": "2026-09-03T10:20:14.882Z",
 "qc_failed": true,
 "qc_note": null,
 "lots_targets": [
 {
 "id": 101,
 "lot_id": 4,
 "target_id": 7,
 "target_name": "Moisture",
 "parameter_id": 3,
 "parameter_name": "Moisture",
 "lower_bound": 10,
 "upper_bound": 12.5,
 "status": "fail",
 "last_evaluated": "2026-09-03T10:15:02.441Z"
 },
 {
 "id": 102,
 "lot_id": 4,
 "target_id": 8,
 "target_name": "Water activity",
 "parameter_id": 5,
 "parameter_name": "Water activity",
 "lower_bound": 0.4,
 "upper_bound": 0.6,
 "status": "pass",
 "last_evaluated": "2026-09-03T10:18:44.019Z"
 }
 ]
}

Bij pass verwacht u "status": "available_for_processing" (of een ongewijzigde non-fail-status) en alle targets "pass".

Lot- & QC-API's (`/api/`)

Geauthenticeerde sessie vereist. Gebruik resource_id uit de webhook als :id / lot_id.

Methode	Endpoint	Doel
`GET`	`/api/lots/:id`	Lot + recept + certificaten + gemeten parameters
`GET`	`/api/lots_targets?lot_id=:id`	Gezaghebbende targetmatrix
`GET`	`/api/parameters`	Parametercatalogus (cachebaar)
`GET`	`/api/targets`	Spec-catalogus (cachebaar; optioneel `?product_id=`)
`GET`	`/api/targets/:id`	Enkele spec
`GET`	`/api/parameters_types`	Parametertype / zonegroepering
`GET`	`/api/recipes/:id`	Volledig recept als lot-embed niet volstaat
`GET`	`/api/lots?rhz=&page=&limit=`	Lijst / sync (optioneel)

Write-back (optioneel; kan QC-webhooks opnieuw emitten):

Methode	Endpoint
`POST`	`/api/lots_parameters`
`PUT`	`/api/lots_parameters/:id`
`POST`	`/api/lots/:id/approveallbooleantargets`

`GET /api/lots/:id`

GET /api/lots/:id

Voorbeeldresponse:

{
 "data": {
 "id": 4,
 "id_tag": "GRE-4",
 "number": "BL-2401",
 "supplier_id": 3,
 "roasthubs_zone_id": 1,
 "unit_id": null,
 "user_id": 4,
 "recipe_id": 10,
 "target_plant_node_id": 12,
 "status": "qc_failed",
 "datetime_qc": "2026-09-03T10:20:14.882Z",
 "qc_failed": true,
 "qc_note": null,
 "erp_id": null,
 "erp_url": null,
 "production_id": null,
 "is_processed_by_plc": false,
 "is_in_warehouse": true,
 "is_available_for_processing": false,
 "needs_cleaning": false,
 "remaining_weight_kg": 847.5,
 "expected_weight_kg_input": 1000,
 "actual_weight_kg_input": 998.2,
 "expected_weight_kg_output": 1000,
 "actual_weight_kg_output": 998.2,
 "note": null,
 "eudr_dds_number": null,
 "created_at": "2026-09-01T08:00:03.114Z",
 "updated_at": "2026-09-03T10:20:14.882Z",
 "recipe": {
 "id": 10,
 "name": "Brazil Cerrado NY2",
 "source_roasthubs_zone_id": 1,
 "note": null
 },
 "target_plant_node": { "name": "Silo A3" },
 "user": { "first_name": "Ada" },
 "certificates": [{ "id": 1, "name": "Organic" }],
 "parameters": [
 {
 "id": 3,
 "name": "Moisture",
 "data_type": "number",
 "parameters_type_id": 1,
 "unit_id": 1,
 "lot_parameter": {
 "id": 9001,
 "value": "13.1",
 "note": null,
 "user_id": 4,
 "created_at": "2026-09-03T10:14:55.220Z"
 }
 },
 {
 "id": 5,
 "name": "Water activity",
 "data_type": "number",
 "parameters_type_id": 1,
 "unit_id": 2,
 "lot_parameter": {
 "id": 9002,
 "value": "0.52",
 "note": null,
 "user_id": 4,
 "created_at": "2026-09-03T10:18:40.091Z"
 }
 }
 ]
 }
}

Koppel parameters[].lot_parameter.value aan targets op parameter_id.

`GET /api/lots_targets?lot_id=:id`

GET /api/lots_targets?lot_id=:id

Voorbeeldresponse:

{
 "data": [
 {
 "id": 101,
 "lot_id": 4,
 "target_id": 7,
 "target_name": "Moisture",
 "parameter_id": 3,
 "parameter_name": "Moisture",
 "lower_bound": 10,
 "upper_bound": 12.5,
 "boolean_target": null,
 "status": "fail",
 "value": null,
 "last_evaluated": "2026-09-03T10:15:02.441Z",
 "created_at": "2026-09-01T08:05:11.102Z"
 },
 {
 "id": 102,
 "lot_id": 4,
 "target_id": 8,
 "target_name": "Water activity",
 "parameter_id": 5,
 "parameter_name": "Water activity",
 "lower_bound": 0.4,
 "upper_bound": 0.6,
 "boolean_target": null,
 "status": "pass",
 "value": null,
 "last_evaluated": "2026-09-03T10:18:44.019Z",
 "created_at": "2026-09-01T08:05:11.220Z"
 }
 ]
}

status: not_evaluated | pass | fail.

`GET /api/parameters`

GET /api/parameters

Voorbeeldresponse:

{
 "data": [
 {
 "id": 3,
 "name": "Moisture",
 "data_type": "number",
 "parameters_type_id": 1,
 "unit_id": 1,
 "regex": null,
 "regex_message": null,
 "parameter_type": {
 "id": 1,
 "name": "Green intake",
 "roasthubs_zone_id": 1
 },
 "lot_parameter": null
 }
 ]
}

Ook: GET /api/parameters_types.

`GET /api/targets` / `GET /api/targets/:id`

GET /api/targets
GET /api/targets?product_id=
GET /api/targets/:id

Voorbeeldlijstresponse:

{
 "data": [
 {
 "id": 7,
 "parameter_id": 3,
 "lower_bound": 10,
 "upper_bound": 12.5,
 "applies_to_all_lots": false,
 "removed": false,
 "recipe_id": 10,
 "plant_node_id": null,
 "recipes_groups_id": null,
 "product_id": null,
 "value": null,
 "parameters": {
 "id": 3,
 "name": "Moisture",
 "data_type": "number",
 "parameters_types": {
 "id": 1,
 "name": "Green intake",
 "roasthubs_zone_id": 1
 }
 }
 }
 ]
}

`GET /api/recipes/:id` (optioneel)

GET /api/recipes/:id

Geeft { "data": { …recipe…, "lines": [ … ] } } terug — gebruik wanneer u componenten / ERP-velden nodig hebt buiten de lot-embed.

`GET /api/lots` (optionele lijst / sync)

GET /api/lots?rhz=&page=&limit=&status=

Voorbeeldresponse:

{
 "meta": { "count": 12 },
 "data": [
 {
 "id": 4,
 "id_tag": "GRE-4",
 "number": "BL-2401",
 "status": "qc_failed",
 "recipe": { "id": 10, "name": "Brazil Cerrado NY2" },
 "targets_qty": 2,
 "targets_qty_pass": 1,
 "targets_qty_fail": 1
 }
 ],
 "parameters": []
}

Met rhz ingesteld kan parameters lots_parameters-rijen voor de pagina bevatten.

Metingen schrijven (optioneel)

POST /api/lots_parameters
Content-Type: application/json

{
 "lot_id": <lot_id>,
 "parameter_id": <parameter_id>,
 "value": "<measured_value>",
 "note": "<optional_note>",
 "user_id": <user_id>
}

PUT /api/lots_parameters/:id
Content-Type: application/json

{
 "value": "<measured_value>",
 "note": "<optional_note>"
}

POST /api/lots/:id/approveallbooleantargets

Deze herevalueren targets en kunnen lot_target_* / lot_qc_* emitten — handel uw eigen events af via webhook-id.

Auth

Webhooks: System → Webhooks
API: geauthenticeerde sessie / org-API-toegang
v2 Swagger (non-QC): {baseUrl}/api/v2/docs

Gerelateerd

docs/webhook-events.md
docs/v2-api.md

Flow​

Webhook-envelope​

QC-events​

lot_target_pass / lot_target_fail​

lot_qc_pass / lot_qc_fail​

Lot- & QC-API's (/api/)​

GET /api/lots/:id​

GET /api/lots_targets?lot_id=:id​

GET /api/parameters​

GET /api/targets / GET /api/targets/:id​

GET /api/recipes/:id (optioneel)​

GET /api/lots (optionele lijst / sync)​

Metingen schrijven (optioneel)​

Auth​

Gerelateerd​

Flow

Webhook-envelope

QC-events

`lot_target_pass` / `lot_target_fail`

`lot_qc_pass` / `lot_qc_fail`

Lot- & QC-API's (`/api/`)

`GET /api/lots/:id`

`GET /api/lots_targets?lot_id=:id`

`GET /api/parameters`

`GET /api/targets` / `GET /api/targets/:id`

`GET /api/recipes/:id` (optioneel)

`GET /api/lots` (optionele lijst / sync)

Metingen schrijven (optioneel)

Auth

Gerelateerd