Roasthubs v2 API
v2 API е типизираният, документиран с OpenAPI HTTP интерфейс, изграден с express-zod-api. Предпочитайте го за нови интеграции. Наследените маршрути под /api/... (без v2) все още съществуват, но не са покрити от този Swagger.
Къде да намерите документацията (Swagger)
На работеща инстанция на Roasthubs:
| Какво | URL |
|---|---|
| Swagger UI | {baseUrl}/api/v2/docs |
| OpenAPI YAML | {baseUrl}/api/v2/docs.yaml |
Примери:
- Локално:
http://localhost:\{PORT\}/api/v2/docs - YAML:
http://localhost:\{PORT\}/api/v2/docs.yaml
Тези маршрути за документация са публични (не се изисква вход). Извикването на самите v2 крайни точки обикновено изисква автентикирана сесия.
OpenAPI спецификацията се генерира при стартиране от същото дърво на маршрутизация като живия API (src/controllers/v2/v2Router.ts → src/openapi.ts).
Базов път
Всички v2 крайни точки са под:
/api/v2/...
Групи крайни точки (преглед)
| Група | Базов път | Предназначение |
|---|---|---|
| Health | /api/v2/health | Проверка на състоянието |
| Productions | /api/v2/production | Списък / създаване / вземане / обновяване / изтриване на продукции |
| Lots | /api/v2/lots/... | Разтоварване на партиди / контейнери (вкл. чрез realisation) |
| Containers | /api/v2/container/:id/emptyToCell | Изпразване на контейнер в клетка |
| Plant nodes | /api/v2/plantNodes/:id | Обновяване на възел на завода |
| Zones | /api/v2/roasthubsZones | CRUD-подобни операции за зони + dump lot/container / stop dump |
| Inventory | /api/v2/inventory/inventorizeWeightedCell | Инвентаризация на претеглена клетка |
| Dosing | /api/v2/dosing/... | Skip / stop dosing order, избор при flow-alarm за празна клетка |
| Shrinkage scale | /api/v2/shrinkageScale/discardBatch | Отхвърляне на партида за печене от shrinkage-scale |
| Scale calibration | /api/v2/scaleCalibration/... | Activate / weights / deactivate / status |
| Connections | /api/v2/connections | Външни връзки + клиентски сертификати |
| Production options | /api/v2/productionRealisationOptions, /api/v2/productionTargetOptions | Вземане/обновяване на realisation и target опции |
| OPC-UA | /api/v2/opcua/read, /api/v2/opcua/write | Четене / запис на OPC-UA тагове |
За схеми на заявки/отговори и точни методи използвайте Swagger UI — това е източникът на истина.
Автентикация
- Документация (
/api/v2/docs,/api/v2/docs.yaml): без защита - Крайни точки: изискват автентикиран потребител (сесия), освен ако конкретен маршрут не е маркиран иначе
Клиентски SDK (frontend)
TypeScript клиент се генерира от същата маршрутизация в:
client/src/express-zod-api-client/v2Client.ts
Използвайте него (или OpenAPI YAML), когато интегрирате от код.