REST · OpenAPI
Infrastructure lookup, pas un wrapper chat
L'API codes erreur CVC auditable par votre backend
Apps mobile, portails et middleware ont besoin de HTTP — pas de MCP. Le REST AskMarcel renvoie codes normalisés, arbres diagnostic disponibles, et abstention explicite en v2 quand le manuel ne se lie pas au SKU.
Pas un agrégateur forums scrapés — réponses liées à la doc constructeur avec abstention facturable vs non facturable dans le contrat.
Le problème métier
Votre app envoie encore des liens PDF — les utilisateurs veulent la réponse dans l'API
Les devs intègrent Google d'abord, puis réalisent que les codes CVC sont ambigus entre marques. Construire une base codes en interne duplique une décennie d'ingestion OEM — et dérive à chaque saison firmware.
Codes ambigus
« E07 » recouvre des dizaines de sens. Il faut un lookup scopé marque, pas une recherche full-text sur les manuels d'installation.
Confiance facturable
La finance demande quels appels étaient de « vraies réponses » vs abstentions. v2 rend cette distinction machine-readable.
Double vélocité
Le produit veut la breadth v1 aujourd'hui ; la conformité veut la provenance v2 demain — sur la même clé API.
Exemple terrain
Lookup portail : code Atlantic 01 sur modèle connu
Un portail constructeur appelle GET /v1/error-codes/atlantic/01 pour widgets legacy, puis migre les comptes premium vers POST /v2/diagnostic avec model_id de la base immatriculations.
v1 renvoie sens + docs liées pour recherche large ; v2 ne renvoie que les gestes dont la page manuel correspond au SKU enregistré — sinon abstention avec code raison pour l'UI.
- OpenAPI sur api.askmarcel.app — synchronisée avec /api/docs/reference
- Tier Developer : 500 mensuel / 50 journalier pour intégration
- Même clé alimente les outils MCP si vous ajoutez des agents plus tard
Extrait redacted à titre d'illustration. L'API live renvoie manufacturer, manual, page et section complets — voir le protocole HVAC-Bench.
Citation illustratif
Toshiba · SHRMi service manual · p. 56
Scénario bench: hvac-bench/lookup-toshiba-1c
{
"brand": "toshiba",
"code": "1C",
"title": "Communication fault (redacted)",
"source": {
"manual": "SHRMi service manual",
"page": 56
},
"billable": true
}{
"brand": "toshiba",
"code": "1C",
"status": "no_exact_source",
"billable": false
}Limites assumées
Périmètre API à planifier
Sémantique v1 vs v2
diagnostic/turn v1 = flux guidé PAC Air/Eau historique sans provenance SKU stricte — documentez quel endpoint votre produit vend.
Harnais à part
Sessions multi-tours sous /v2/diagnostic-sessions (Beta) — pas dans un seul POST /v2/diagnostic.
Rate limits
Quotas tier Developer pour QA et pilotes — volumes prod nécessitent plan commercial.
Deux périmètres
Ingénieur plateforme vs product owner
Périmètre A — Backend & API
Vous portez clients OpenAPI et SLA
Vous voulez chemins stables, erreurs typées et un contrat public surface validé en CI — pas un guide PDF d'intégration 2022.
- Chemins GA : /v1/search, /v1/error-codes/{brand}/{code}, /v2/diagnostic
- public-surface.snapshot.json validé en CI avant déploiement
- Référence Scalar embarquée sur /api/docs/reference
Périmètre B — Produit & monétisation
Vous packagez le lookup pour clients finaux
Vous décidez si le portail affiche « sens seul » ou diagnostic facturable — AskMarcel fournit signaux d'abstention pour aligner le COGS.
- Abstention v2 non facturable évite surprises en fin de mois
- Guide which-api pour sales engineering
- Tarif pilote avant publication liste
Flux d'intégration
De l'OpenAPI aux clés production
- 1
Lire which-api
Choisissez breadth v1, provenance v2 ou sessions Harnais avant de coder — évite le refactor semaine 3.
- 2
Smoke test clé Developer
Frappez /v1/search et un code marque de votre top trafic ; logguez latence et champs citation.
- 3
Ajouter v2 quand SKU disponible
Branchez model_id depuis votre base actifs ; traitez abstention en UI comme état de premier niveau.
- 4
Promouvoir quota commercial
Contact pilote quand le volume dépasse tier Developer — mêmes endpoints, limites supérieures.
Preuve
Contrat public surface, validé en CI
Chemins REST GA et outils MCP sont listés dans public-surface.snapshot.json — validé en CI contre l'endpoint public live avant chaque déploiement.
Ouvrir détails corpus & bench7
Chemins REST GA
400k+
Codes normalisés marque
94 %
Retrieval page manuel (bench)
Intégrez le lookup CVC en jours, pas en trimestres
Tirez l'OpenAPI, émettez une clé Developer, shippez v1 — ajoutez provenance v2 quand le registre actifs est prêt.