Quelle API utiliser ?

Trois surfaces, un moteur

https://api.askmarcel.app expose REST v1 (lookup), REST v2 (provenance SKU + sessions Harnais Beta) et un serveur MCP sur https://mcp.askmarcel.app (protocole 2025-06-18, manifeste 1.3.0-beta.1). Deux périmètres distincts : lookup mondial (400k+ codes) vs Harnais Beta (5 marques ancres, familles pac_air_eau / pac_air_air, pack 0.0.1).

Matrice de décision

Utilisez cette table avant d’intégrer. Les chemins et outils listés sont le contrat public (snapshot WebApp).

• [Live] Lookup large, automatisations, intégrations historiques
• Quand : Vous avez besoin d’un code erreur, d’une recherche documentaire ou d’un diagnostic one-shot sans exiger la provenance SKU stricte.
• REST : /v1/search, /v1/error-codes/{brand}/{code}, /v1/diagnostic, /v1/diagnostic/turn
• MCP : get_error_code, diagnose, diagnose_guided, search_technical_docs
• Limite : Pas de provenance SKU stricte ; diagnostic/turn = guidé PAC Air/Eau historique.
• [Live] Agents et logiciels qui doivent citer ou s’abstenir
• Quand : Vous devez répondre uniquement avec un manuel exact pour le SKU — sinon abstention (non facturable).
• REST : /v2/diagnostic, /v2/models/resolve, /v2/models/{model_id}/coverage
• MCP : diagnose_v2, resolve_model, get_model_coverage
• Limite : Pas une session stateful multi-tours.
• [Beta] GMAO, FSM, cockpit — diagnostic guidé journalisé
• Quand : Vous voulez le Harnais : contrôle suivant sûr, journal de session et reprise par session_id.
• REST : /v2/diagnostic-sessions, /v2/diagnostic-sessions/{session_id}, /v2/diagnostic-sessions/{session_id}/responses, /v2/diagnostic-sessions/{session_id}/close, /v2/diagnostic-sessions/{session_id}/summary
• MCP : start_diagnostic, respond_to_diagnostic, get_diagnostic, close_diagnostic (+1)
• Limite : Beta — 5 marques ancres, PAC Air/Eau + Air/Air ; pas les 400k codes en profondeur.
• [Live] ChatGPT, Claude, agents maison
• Quand : Votre agent appelle des outils MCP sur mcp.askmarcel.app (protocole 2025-06-18).
• REST : — (MCP uniquement)
• MCP : search_technical_docs, get_procedure, get_error_code, get_product_sheet (+6)
• Limite : OAuth actuel : pas de scope diagnostic.run pour les sessions Beta.

Périmètre Harnais Beta

Le Harnais ne couvre pas le dictionnaire mondial des codes. Beta fermée : panasonic, daikin, atlantic, mitsubishi-electric, gree ; 148/958 codes avec chemin causal (~15%). Les packs Beta 0.0.1 sont mutables : une session reprise utilise le contenu courant du pack. Le résultat fabricant du démarrage reste journalisé.

Abstention et facturation

v2 / diagnose_v2 : si aucun manuel exact pour le SKU → diagnostic null, status no_exact_source ou model_ambiguous — non facturable. v1 peut retourner une réponse sourcée plus large ; pour les agents qui doivent citer, préférez v2.

MCP et OAuth

OAuth actuel : scopes docs.read, catalog.read, pdf.read — pas de diagnostic.run pour les outils session Beta via OAuth seul. Protocole supporté : 2025-06-18 uniquement (pas de spec 2026-07-28 tant que non déployée).

Suite

Quickstart → clé Developer → premier appel sourcé. Pour acheter ou cadrer un pilote : REST terrain /solutions/hvac-field-service-software ; REST support /solutions/hvac-support-automation ; codes erreur /solutions/hvac-error-code-api ; MCP /solutions/hvac-mcp-server ; Harnais /solutions/hvac-diagnostic-harness.

• Démarrage rapide : /api/docs/quickstart
• REST détaillé : /api/docs/rest
• MCP : /api/docs/mcp
• Contrat machine : https://api.askmarcel.app/v1/public-surface.json