API Roasthubs v2
L'API v2 est la surface HTTP typée, documentée en OpenAPI, construite avec express-zod-api. Préférez-la pour les nouvelles intégrations. Les routes legacy sous /api/... (sans v2) existent encore mais ne sont pas couvertes par ce Swagger.
Où trouver la documentation (Swagger)
Sur une instance Roasthubs en cours d'exécution :
| Élément | URL |
|---|---|
| Swagger UI | {baseUrl}/api/v2/docs |
| OpenAPI YAML | {baseUrl}/api/v2/docs.yaml |
Exemples :
- Local :
http://localhost:\{PORT\}/api/v2/docs - YAML :
http://localhost:\{PORT\}/api/v2/docs.yaml
Ces routes de documentation sont publiques (aucune connexion requise). L'appel des endpoints v2 réels nécessite normalement une session authentifiée.
La spécification OpenAPI est générée au démarrage à partir du même arbre de routage que l'API live (src/controllers/v2/v2Router.ts → src/openapi.ts).
Chemin de base
Tous les endpoints v2 se trouvent sous :
/api/v2/...
Groupes d'endpoints (aperçu)
| Groupe | Chemin de base | Objectif |
|---|---|---|
| Health | /api/v2/health | Contrôle de santé |
| Productions | /api/v2/production | Lister / créer / obtenir / mettre à jour / supprimer des productions |
| Lots | /api/v2/lots/... | Décharger des lots / conteneurs (y compris via réalisation) |
| Containers | /api/v2/container/:id/emptyToCell | Vider un conteneur dans une cellule |
| Plant nodes | /api/v2/plantNodes/:id | Mettre à jour un nœud d'usine |
| Zones | /api/v2/roasthubsZones | Zones CRUD-ish + dump lot/conteneur / arrêter le dump |
| Inventory | /api/v2/inventory/inventorizeWeightedCell | Inventorier une cellule pesée |
| Dosing | /api/v2/dosing/... | Ignorer / arrêter un ordre de dosage, choix cellule vide pour alarme de flux |
| Shrinkage scale | /api/v2/shrinkageScale/discardBatch | Rejeter un batch de balance de retrait |
| Scale calibration | /api/v2/scaleCalibration/... | Activer / poids / désactiver / statut |
| Connections | /api/v2/connections | Connexions externes + certificats clients |
| Production options | /api/v2/productionRealisationOptions, /api/v2/productionTargetOptions | Obtenir/mettre à jour les options de réalisation et de cible |
| OPC-UA | /api/v2/opcua/read, /api/v2/opcua/write | Lire / écrire des tags OPC-UA |
Pour les schémas requête/réponse et les méthodes exactes, utilisez Swagger UI — c'est la source de vérité.
Authentification
- Docs (
/api/v2/docs,/api/v2/docs.yaml) : non protégés - Endpoints : nécessitent un utilisateur authentifié (session), sauf si une route spécifique est marquée autrement
SDK client (frontend)
Un client TypeScript est généré à partir du même routage dans :
client/src/express-zod-api-client/v2Client.ts
Utilisez celui-ci (ou le YAML OpenAPI) lors de l'intégration depuis le code.