Quality control integration
Integrate an external QA / lab system with Roasthubs via QC webhooks and legacy /api/ reads.
Lot id_tag values are generated as {first 3 letters of zone name}-{sequence} (e.g. 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
- Subscribe to the four QC events under System → Webhooks.
- On delivery, use
resource_idas the lot id (confirm withdata.lot_idwhen present). - Load lot / QC detail with the
/api/calls below (no QC lot GET on v2 today). - Deduplicate on webhook
id; return 2xx quickly.
Webhook envelope
POST JSON, retries with exponential backoff. id is the idempotency key.
{
"id": 18402,
"type_id": "lot_qc_fail",
"user_id": 4,
"resource_id": 4,
"roasthubs_zone_id": 1,
"data": {}
}
| Field | Meaning |
|---|---|
id | Event id (dedupe) |
type_id | Event name below |
resource_id | Lot id for follow-up GETs |
roasthubs_zone_id | Zone of the lot |
data | Event payload |
QC events
lot_target_pass / lot_target_fail
Fired when one target on a lot is evaluated (after POST/PUT /api/lots_parameters, or boolean approve).
data is the updated lots_targets row:
{
"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"
}
Use "pass" or "fail" in status depending on the event.
Boolean bulk-approve may instead send:
{ "status": "pass", "target_id": 101 }
In that path resource_id can be the target id — prefer data.lot_id / a follow-up GET /api/lots_targets when unsure.
lot_qc_pass / lot_qc_fail
Fired when every target on the lot has been evaluated. Fail if any target failed (status → qc_failed).
data is the lot including 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"
}
]
}
On pass, expect "status": "available_for_processing" (or unchanged non-fail status) and all targets "pass".
Lot & QC APIs (/api/)
Authenticated session required. Use resource_id from the webhook as :id / lot_id.
| Method | Endpoint | Purpose |
|---|---|---|
GET | /api/lots/:id | Lot + recipe + certificates + measured parameters |
GET | /api/lots_targets?lot_id=:id | Authoritative target matrix |
GET | /api/parameters | Parameter catalogue (cacheable) |
GET | /api/targets | Spec catalogue (cacheable; optional ?product_id=) |
GET | /api/targets/:id | Single spec |
GET | /api/parameters_types | Parameter type / zone grouping |
GET | /api/recipes/:id | Full recipe if lot embed is not enough |
GET | /api/lots?rhz=&page=&limit= | List / sync (optional) |
Write-back (optional; may re-emit QC webhooks):
| Method | Endpoint |
|---|---|
POST | /api/lots_parameters |
PUT | /api/lots_parameters/:id |
POST | /api/lots/:id/approveallbooleantargets |
GET /api/lots/:id
GET /api/lots/:id
Example response:
{
"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"
}
}
]
}
}
Join parameters[].lot_parameter.value to targets on parameter_id.
GET /api/lots_targets?lot_id=:id
GET /api/lots_targets?lot_id=:id
Example response:
{
"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
Example response:
{
"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
}
]
}
Also: GET /api/parameters_types.
GET /api/targets / GET /api/targets/:id
GET /api/targets
GET /api/targets?product_id=
GET /api/targets/:id
Example list response:
{
"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
Returns { "data": { …recipe…, "lines": [ … ] } } — use when you need components / ERP fields beyond the lot embed.
GET /api/lots (optional list / sync)
GET /api/lots?rhz=&page=&limit=&status=
Example response:
{
"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": []
}
With rhz set, parameters may include lots_parameters rows for the page.
Write measurements (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
These re-evaluate targets and can emit lot_target_* / lot_qc_* — handle your own events via webhook id.
Auth
- Webhooks: System → Webhooks
- API: authenticated session / org API access
- v2 Swagger (non-QC):
{baseUrl}/api/v2/docs
Related
docs/webhook-events.mddocs/v2-api.md