Интеграция за контрол на качеството

Интегрирайте външна QA / лабораторна система с Roasthubs чрез QC уебхукове и наследени /api/ четения.

Стойностите id_tag на партидите се генерират като {първите 3 букви от името на зоната}-{последователност} (напр. green → GRE-4, roast → ROA-12).

Поток

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

Абонирайте се за четирите QC събития под System → Webhooks.
При доставка използвайте resource_id като id на партидата (потвърдете с data.lot_id, когато е налично).
Заредете детайли за партида / QC с /api/ повикванията по-долу (в момента няма QC lot GET на v2).
Дедупликирайте по id на уебхука; връщайте 2xx бързо.

Обвивка на уебхука

POST JSON, повторни опити с експоненциален backoff. id е ключът за идемпотентност.

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

Поле	Значение
`id`	Id на събитието (дедупликация)
`type_id`	Име на събитието по-долу
`resource_id`	Id на партидата за последващи GET
`roasthubs_zone_id`	Зона на партидата
`data`	Payload на събитието

QC събития

`lot_target_pass` / `lot_target_fail`

Задейства се, когато една цел върху партида е оценена (след POST/PUT /api/lots_parameters или булево одобрение).

data е обновеният ред от 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,
 "boolean_target": null,
 "status": "fail",
 "value": null,
 "last_evaluated": "2026-09-03T10:15:02.441Z",
 "created_at": "2026-09-01T08:05:11.102Z"
}

Използвайте "pass" или "fail" в status според събитието.

Булевото масово одобрение може вместо това да изпрати:

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

В този път resource_id може да е id на целта — предпочитайте data.lot_id / последващ GET /api/lots_targets, когато не сте сигурни.

`lot_qc_pass` / `lot_qc_fail`

Задейства се, когато всяка цел върху партидата е оценена. Fail, ако някоя цел е неуспешна (status → qc_failed).

data е партидата, включително 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"
 }
 ]
}

При pass очаквайте "status": "available_for_processing" (или непроменен статус, различен от fail) и всички цели "pass".

API за партиди и QC (`/api/`)

Изисква се автентикирана сесия. Използвайте resource_id от уебхука като :id / lot_id.

Метод	Крайна точка	Предназначение
`GET`	`/api/lots/:id`	Партида + рецепта + сертификати + измерени параметри
`GET`	`/api/lots_targets?lot_id=:id`	Авторитетна матрица на целите
`GET`	`/api/parameters`	Каталог на параметрите (кешируем)
`GET`	`/api/targets`	Каталог на спецификациите (кешируем; по желание `?product_id=`)
`GET`	`/api/targets/:id`	Единична спецификация
`GET`	`/api/parameters_types`	Групиране по тип параметър / зона
`GET`	`/api/recipes/:id`	Пълна рецепта, ако вграждането в партидата не е достатъчно
`GET`	`/api/lots?rhz=&page=&limit=`	Списък / синхронизация (по желание)

Обратен запис (по желание; може отново да излъчи QC уебхукове):

Метод	Крайна точка
`POST`	`/api/lots_parameters`
`PUT`	`/api/lots_parameters/:id`
`POST`	`/api/lots/:id/approveallbooleantargets`

`GET /api/lots/:id`

GET /api/lots/:id

Примерен отговор:

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

Свържете parameters[].lot_parameter.value с целите по parameter_id.

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

GET /api/lots_targets?lot_id=:id

Примерен отговор:

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

Примерен отговор:

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

Също: GET /api/parameters_types.

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

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

Примерен отговор на списък:

{
 "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` (по желание)

GET /api/recipes/:id

Връща { "data": { …recipe…, "lines": [ … ] } } — използвайте, когато ви трябват компоненти / ERP полета отвъд вграждането в партидата.

`GET /api/lots` (по желание списък / синхронизация)

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

Примерен отговор:

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

С зададен rhz, parameters може да включва редове lots_parameters за страницата.

Запис на измервания (по желание)

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

Тези преоценяват целите и могат да излъчат lot_target_* / lot_qc_* — обработвайте собствените си събития чрез id на уебхука.

Автентикация

Уебхукове: System → Webhooks
API: автентикирана сесия / API достъп на организацията
v2 Swagger (без QC): {baseUrl}/api/v2/docs

Свързани

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

Поток​

Обвивка на уебхука​

QC събития​

lot_target_pass / lot_target_fail​

lot_qc_pass / lot_qc_fail​

API за партиди и QC (/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 (по желание)​

GET /api/lots (по желание списък / синхронизация)​

Запис на измервания (по желание)​

Автентикация​

Свързани​

Поток

Обвивка на уебхука

QC събития

`lot_target_pass` / `lot_target_fail`

`lot_qc_pass` / `lot_qc_fail`

API за партиди и QC (`/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` (по желание)

`GET /api/lots` (по желание списък / синхронизация)

Запис на измервания (по желание)

Автентикация

Свързани