L'API

L'API est là pour le moment où un outil de devis veut le débit et le retour d'une étude sans que quelqu'un recopie des chiffres d'un rapport, ou où un gestionnaire de flotte veut envoyer les données d'exploitation quotidiennes sans tableur. Elle est disponible sur Team et Enterprise, sur auddomate.com comme sur les installations auto-hébergées. Tout ce qu'elle renvoie est ce que vous voyez dans l'application : la même flotte, les mêmes hypothèses, la même arithmétique.

#Clés

Les propriétaires créent des clés sous Réglages → Clés API. Nommez chacune d'après le système qui l'utilisera, cochez ce qu'elle peut faire, et copiez la clé quand elle apparaît — elle n'est affichée qu'une fois et stockée hachée. Une clé a une ou plusieurs portées :

read

Études, résultats, machines et catalogue. Chaque clé l'a.

telemetry

Écrire des lignes de télémétrie dans une étude.

audit

Lire le journal d'audit.

Révoquez une clé depuis la même page ; tout ce qui l'utilise encore reçoit 401 à partir de cet instant. La création et la révocation de clés sont elles-mêmes écrites dans le journal d'audit. Jusqu'à vingt clés actives par organisation.

#L'appeler

Chaque requête porte la clé en jeton bearer. L'adresse de base est votre adresse Auddomate suivie de /api/v1.

curl -H "Authorization: Bearer aud_…" https://auddomate.com/api/v1/me

Si quelque chose entre vous et le serveur supprime l'en-tête Authorization, envoyez-le plutôt sous la forme X-Api-Key: aud_…. Les réponses sont en JSON avec une forme stable :

{ "ok": true, "data": …, "meta": { "page": 1, "per_page": 50, "total": 132, "pages": 3 } }
{ "ok": false, "error": "not_found", "message": "No study ST-9999 in this organisation." }

Les listes se paginent avec ?page= et ?per_page= (jusqu'à 200). Les heures sont l'heure locale du serveur au format YYYY-MM-DD HH:MM:SS ; les longueurs sont en millimètres, les distances en mètres, les cadences par heure ou par jour, exactement comme dans l'application. Chaque clé peut faire 300 requêtes par minute ; au-delà vous recevez 429 avec un en-tête Retry-After.

#Points d'accès

GET /api/v1/me

L'organisation, le nom et les portées de la clé, l'édition et la limite de débit. Utilisez-le pour vérifier qu'une clé fonctionne.

GET /api/v1/studies

Chaque étude : référence, nom, site, client, statut, le verdict de débit et la marge du scénario courant, et le nombre d'unités de sa flotte. Filtrez avec ?status=, ?client= ou ?updated_since=2026-09-01.

GET /api/v1/studies/{ref}

Une étude complète, par référence (ST-1001) ou par id : le plan (fichier, échelle, étendue, combien de rayonnages, allées, quais et obstacles), et chaque scénario avec ses lignes de flotte, hypothèses, résultat de débit ligne par ligne, le contrôle d'allée face à la machine la plus exigeante, et quelle machine c'était.

GET /api/v1/studies/{ref}/telemetry

Les données d'exploitation d'une étude, une ligne par machine et par jour.

GET /api/v1/studies/{ref}/pdf

Le rapport en fichier PDF, généré sur le serveur. ?lang= et ?units=imperial choisissent la langue et les unités. /versions/{n}/pdf pour une version enregistrée.

GET /api/v1/studies/{ref}/versions

Les versions enregistrées d'une étude, la plus récente en premier ; /versions/{n} en renvoie une complète sous la même forme que l'étude elle-même, et ?diff=1 ajoute ce qui a changé depuis.

POST /api/v1/studies/{ref}/telemetry

Écrire des données d'exploitation. Nécessite la portée telemetry. Envoyez {"rows": [...]}, jusqu'à 5 000 lignes ; chaque ligne nomme la machine par machine_id ou machine (son nom exact), un day, et n'importe lesquels de moves, run_minutes, idle_minutes, distance_km, faults. Une ligne pour une machine et un jour qui existent déjà est remplacée. La réponse dit combien ont été écrites et liste les cinquante premières lignes ignorées et pourquoi.

GET /api/v1/machines

Votre bibliothèque de machines, chaque profil avec ses chiffres et, pour les modèles du catalogue, la fiche technique dont il provient. /machines/{id} pour un seul.

GET /api/v1/catalogue

Le catalogue de vraies marques et de vrais modèles avec leurs fiches techniques sources. Filtrez avec ?vendor= ou ?class=.

GET /api/v1/audit

Le journal d'audit, le plus récent en premier. Nécessite la portée audit. Filtrez avec ?group=, ?from=, ?to=, ?q=.

#À quoi ressemble une étude

{
  "ref": "ST-1002", "name": "Cold store aisle audit", "status": "review",
  "plan": { "file": "cold-store.dxf", "scale": { "mm_per_unit": 1, "source": "dxf" },
            "extent_mm": { "width": 61000, "height": 45000 },
            "shapes": { "rack": 6, "aisle": 5, "dock": 1, "block": 3 } },
  "scenarios": [ {
    "name": "Base", "current": true,
    "fleet": [ { "machine": "VNA turret, 1.0 t", "class": "vna", "qty": 3, "shifts": 2 } ],
    "assumptions": { "moves_required": 2110, "hours_per_shift": 8, "days_per_year": 300,
                     "distance_m": 14, "distance_source": "plan", "handling_s": 55 },
    "throughput": { "verdict": "meets", "moves_per_day": 3024.6, "required_per_day": 2110,
                    "headroom_per_day": 914.6, "utilisation_pct": 69.8, "lines": [ … ] },
    "aisles": { "verdict": "fail", "aisle_min_mm": 2100, "narrowest_mm": 1800, "aisles": 5, "below": 5 },
    "checked_against": { "machine": "Pallet truck, pedestrian 1.6 t", "aisle_min_mm": 2100 }
  } ]
}

throughput.verdict vaut l'un de meets, short, nofleet, nodistance ou notarget ; aisles.verdict l'un de pass, fail, noplan, noscale, noaisles ou none. distance_source dit si la distance de trajet a été saisie ou dérivée du plan, comme le fait la page Simulation.

#Envoyer des données d'exploitation

curl -X POST https://auddomate.com/api/v1/studies/ST-1002/telemetry \
  -H "Authorization: Bearer aud_…" -H "Content-Type: application/json" \
  -d '{"rows": [
        {"machine": "VNA turret, 1.0 t", "day": "2026-09-01", "moves": 412, "run_minutes": 480, "idle_minutes": 60, "distance_km": 18.4, "faults": 1},
        {"machine_id": 327, "day": "2026-09-02", "moves": 390}
      ]}'

{ "ok": true, "data": { "written": 2, "skipped": 0, "errors": [] } }

#Erreurs

401 unauthorised

Pas de clé, ou une clé que nous ne reconnaissons pas.

401 revoked

La clé a été révoquée ; le message dit quand.

403 plan

L'organisation est sur Gratuit ou Studio.

403 scope

La clé n'a pas la portée dont le point d'accès a besoin.

404 not_found

Pas d'étude, de machine ou de point d'accès de ce nom.

400 json / empty

Le corps n'était pas un objet JSON, ou n'avait pas de lignes.

413 too_many

Plus de 5 000 lignes dans une seule requête de télémétrie.

429 rate_limited

Plus de 300 requêtes en une minute. Attendez Retry-After secondes.

#Gestion des versions

Le chemin porte la version. Des champs sont ajoutés à v1 avec le temps mais jamais renommés ni retirés ; tout ce qui casserait un client devient v2, v1 restant en service en parallèle pendant au moins un an. Les changements sont listés dans le journal des versions comme tout le reste.