API v2 de Roasthubs
La API v2 es la superficie HTTP tipada y documentada con OpenAPI, construida con express-zod-api. Prefiérala para integraciones nuevas. Las rutas heredadas bajo /api/... (sin v2) siguen existiendo pero no están cubiertas por este Swagger.
Dónde encontrar la documentación (Swagger)
En una instancia de Roasthubs en ejecución:
| Qué | URL |
|---|---|
| Swagger UI | {baseUrl}/api/v2/docs |
| OpenAPI YAML | {baseUrl}/api/v2/docs.yaml |
Ejemplos:
- Local:
http://localhost:\{PORT\}/api/v2/docs - YAML:
http://localhost:\{PORT\}/api/v2/docs.yaml
Estas rutas de documentación son públicas (no requieren inicio de sesión). Llamar a los endpoints v2 reales normalmente requiere una sesión autenticada.
La especificación OpenAPI se genera al arrancar a partir del mismo árbol de rutas que la API en vivo (src/controllers/v2/v2Router.ts → src/openapi.ts).
Ruta base
Todos los endpoints v2 viven bajo:
/api/v2/...
Grupos de endpoints (resumen)
| Grupo | Ruta base | Propósito |
|---|---|---|
| Health | /api/v2/health | Comprobación de salud |
| Productions | /api/v2/production | Listar / crear / obtener / actualizar / eliminar producciones |
| Lots | /api/v2/lots/... | Descargar lotes / contenedores (incl. vía realisation) |
| Containers | /api/v2/container/:id/emptyToCell | Vaciar un contenedor en una celda |
| Plant nodes | /api/v2/plantNodes/:id | Actualizar un nodo de planta |
| Zones | /api/v2/roasthubsZones | CRUD-ish de zonas + dump de lote/contenedor / detener dump |
| Inventory | /api/v2/inventory/inventorizeWeightedCell | Inventariar una celda con báscula |
| Dosing | /api/v2/dosing/... | Omitir / detener orden de dosificación, elección de celda vacía por alarma de flujo |
| Shrinkage scale | /api/v2/shrinkageScale/discardBatch | Descartar una tanda de báscula de merma |
| Scale calibration | /api/v2/scaleCalibration/... | Activar / pesos / desactivar / estado |
| Connections | /api/v2/connections | Conexiones externas + certificados de cliente |
| Production options | /api/v2/productionRealisationOptions, /api/v2/productionTargetOptions | Obtener/actualizar opciones de realisation y destino |
| OPC-UA | /api/v2/opcua/read, /api/v2/opcua/write | Leer / escribir etiquetas OPC-UA |
Para esquemas de petición/respuesta y métodos exactos, use Swagger UI: es la fuente de verdad.
Autenticación
- Docs (
/api/v2/docs,/api/v2/docs.yaml): sin protección - Endpoints: requieren un usuario autenticado (sesión), salvo que una ruta concreta indique lo contrario
SDK de cliente (frontend)
Se genera un cliente TypeScript a partir del mismo enrutado en:
client/src/express-zod-api-client/v2Client.ts
Úselo (o el YAML de OpenAPI) al integrar desde código.