Qualitätskontroll-Integration

Integrieren Sie ein externes QA-/Laborsystem mit Roasthubs über QC-Webhooks und Legacy-/api/-Lesezugriffe.

Charge-id_tag-Werte werden als {erste 3 Buchstaben des Zonennamens}-{Sequenz} erzeugt (z. B. green → GRE-4, roast → ROA-12).

Ablauf

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

Abonnieren Sie die vier QC-Ereignisse unter System → Webhooks.
Bei der Zustellung verwenden Sie resource_id als Charge-ID (bei Vorhandensein mit data.lot_id bestätigen).
Laden Sie Charge-/QC-Details mit den /api/-Aufrufen unten (heute kein QC-Charge-GET auf v2).
Deduplizieren Sie über die Webhook-id; antworten Sie schnell mit 2xx.

Webhook-Hülle

POST JSON, Retries mit exponentiellem Backoff. id ist der Idempotenzschlüssel.

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

Feld	Bedeutung
`id`	Ereignis-ID (Deduplizierung)
`type_id`	Ereignisname unten
`resource_id`	Charge-ID für Folge-GETs
`roasthubs_zone_id`	Zone der Charge
`data`	Ereignis-Payload

QC-Ereignisse

`lot_target_pass` / `lot_target_fail`

Wird ausgelöst, wenn ein Ziel an einer Charge bewertet wird (nach POST/PUT /api/lots_parameters oder boolescher Freigabe).

data ist die aktualisierte lots_targets-Zeile:

{
 "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"
}

Verwenden Sie "pass" oder "fail" in status je nach Ereignis.

Bei boolescher Sammelfreigabe kann stattdessen gesendet werden:

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

In diesem Pfad kann resource_id die Ziel-ID sein — bevorzugen Sie data.lot_id / ein Folge-GET /api/lots_targets, wenn unsicher.

`lot_qc_pass` / `lot_qc_fail`

Wird ausgelöst, wenn jedes Ziel der Charge bewertet wurde. Fehlschlag, wenn irgendein Ziel fehlgeschlagen ist (status → qc_failed).

data ist die Charge einschließlich 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"
 }
 ]
}

Bei Bestehen erwarten Sie "status": "available_for_processing" (oder unveränderten Nicht-Fail-Status) und alle Ziele "pass".

Charge- & QC-APIs (`/api/`)

Authentifizierte Sitzung erforderlich. Verwenden Sie resource_id aus dem Webhook als :id / lot_id.

Methode	Endpunkt	Zweck
`GET`	`/api/lots/:id`	Charge + Rezept + Zertifikate + gemessene Parameter
`GET`	`/api/lots_targets?lot_id=:id`	Maßgebliche Zielmatrix
`GET`	`/api/parameters`	Parameterkatalog (cachebar)
`GET`	`/api/targets`	Spezifikationskatalog (cachebar; optional `?product_id=`)
`GET`	`/api/targets/:id`	Einzelne Spezifikation
`GET`	`/api/parameters_types`	Parametertyp- / Zonengruppierung
`GET`	`/api/recipes/:id`	Vollständiges Rezept, falls Charge-Embed nicht ausreicht
`GET`	`/api/lots?rhz=&page=&limit=`	Liste / Sync (optional)

Write-back (optional; kann QC-Webhooks erneut auslösen):

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

`GET /api/lots/:id`

GET /api/lots/:id

Beispielantwort:

{
 "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"
 }
 }
 ]
 }
}

Verknüpfen Sie parameters[].lot_parameter.value mit Zielen über parameter_id.

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

GET /api/lots_targets?lot_id=:id

Beispielantwort:

{
 "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

Beispielantwort:

{
 "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
 }
 ]
}

Außerdem: GET /api/parameters_types.

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

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

Beispiel-Listenantwort:

{
 "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` (optional)

GET /api/recipes/:id

Gibt { "data": { …recipe…, "lines": [ … ] } } zurück — nutzen Sie das, wenn Sie Komponenten / ERP-Felder über das Charge-Embed hinaus brauchen.

`GET /api/lots` (optionale Liste / Sync)

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

Beispielantwort:

{
 "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": []
}

Mit gesetztem rhz kann parameters lots_parameters-Zeilen für die Seite enthalten.

Messwerte schreiben (optional)

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

Diese bewerten Ziele neu und können lot_target_* / lot_qc_* auslösen — handhaben Sie Ihre eigenen Ereignisse über die Webhook-id.

Auth

Webhooks: System → Webhooks
API: authentifizierte Sitzung / Organisations-API-Zugriff
v2 Swagger (nicht QC): {baseUrl}/api/v2/docs

Verwandt

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

Ablauf​

Webhook-Hülle​

QC-Ereignisse​

lot_target_pass / lot_target_fail​

lot_qc_pass / lot_qc_fail​

Charge- & QC-APIs (/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 (optional)​

GET /api/lots (optionale Liste / Sync)​

Messwerte schreiben (optional)​

Auth​

Verwandt​

Ablauf

Webhook-Hülle

QC-Ereignisse

`lot_target_pass` / `lot_target_fail`

`lot_qc_pass` / `lot_qc_fail`

Charge- & QC-APIs (`/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` (optional)

`GET /api/lots` (optionale Liste / Sync)

Messwerte schreiben (optional)

Auth

Verwandt