Documentation de l'API VerifierMonDevis

Tout ce qu'il faut pour envoyer un devis et lire son analyse. Cette page est générée depuis la description OpenAPI de l'API : elle ne peut pas s'en écarter. Elle existe aussi en Markdown, pour un assistant de code.

Présentation

Analyse de devis de travaux : entreprise vérifiée aux registres, clauses, risques, et prix quand ils sont comparables. Une analyse prend en général 1 à 3 minutes. Chaque analyse prête consomme un crédit ; un document refusé le rend (5 par 24 h au plus), une analyse en échec aussi (20 par 24 h au plus). Débit : 10 envois par minute, refusés compris, et 5 analyses en cours par compte.

  • Adresse de base : https://www.verifiermondevis.fr/api/v1. Requêtes et réponses en JSON, sauf le dépôt du devis (multipart/form-data).
  • Le traitement est asynchrone : vous déposez le devis (réponse 202 avec son id), puis vous lisez l'analyse quand son statut vaut ready, ou vous recevez un webhook.
  • Une partie des analyses est en plus relue par un expert : le verdict arrive tout de suite, marqué provisoire, et la version relue le remplace à la même adresse sous 24 h ouvrées (voir Revue humaine).
  • La réponse dit ce que la page de l'analyse affiche, par les mêmes règles : décision, entreprise, points vérifiés, leviers, message à l'artisan.
  • Description complète au format OpenAPI 3.1 : https://www.verifiermondevis.fr/api/v1/openapi.json. Cette documentation existe aussi en Markdown : https://www.verifiermondevis.fr/developpeurs/documentation.md.

Démarrage rapide

  • Créez votre compte sur verifiermondevis.fr et confirmez votre adresse e-mail (lien reçu à l'inscription).
  • Sur votre espace développeur, acceptez les conditions d'utilisation de l'API et créez une clé. Elle ne s'affiche qu'une fois : copiez-la. Votre première clé vous offre 3 analyses.
  • Déposez un devis, puis lisez l'analyse quand son statut vaut ready :
export VMD_API_KEY="vmd_VOTRE_CLE"

curl -X POST "https://www.verifiermondevis.fr/api/v1/analyses" \
  -H "Authorization: Bearer $VMD_API_KEY" \
  -F "file=@devis.pdf"
# Réponse : {"id":"…","status":"queued"}

curl "https://www.verifiermondevis.fr/api/v1/analyses/ID_RENDU_CI_DESSUS" \
  -H "Authorization: Bearer $VMD_API_KEY"

Regardez revue.statut dans la réponse. S'il vaut en_revue, un expert relit l'analyse : le verdict est provisoire, et la version relue arrive à la même adresse sous 24 h ouvrées. revue.explication le dit en une phrase, et la section Revue humaine explique comment être prévenu.

Authentification

Chaque requête porte votre clé dans l'en-tête Authorization, précédée de Bearer. Une clé commence par vmd_.

Authorization: Bearer vmd_VOTRE_CLE
  • Créez vos clés sur votre espace développeur, après avoir créé votre compte et confirmé votre adresse e-mail. Une clé ne s'affiche qu'une fois, à sa création : copiez-la tout de suite.
  • Une clé n'ouvre que les analyses de votre compte. Gardez-la côté serveur : jamais dans une application mobile, une page web ou un dépôt de code.
  • Une clé révoquée est refusée dès l'appel suivant (401). En cas de doute, révoquez-la et créez-en une autre.

POST /analyses : Déposer un devis

Adresse : https://www.verifiermondevis.fr/api/v1/analyses

Paramètres

NomOùObligatoireTypeDescription
Idempotency-Keyen-têtenontexte, 200 caractères au plusRejouer la même clé rend l'analyse déjà créée, sans nouveau débit. Si elle est en échec, refusée ou effacée, un nouvel envoi est créé.

Corps (multipart/form-data)

ChampObligatoireTypeDescription
fileouifichierPDF, JPEG ou PNG, 4 Mo au plus, 15 pages au plus.
external_refnontexte, 200 caractères au plusVotre référence (un numéro de dossier, par exemple), rendue telle quelle dans l'analyse et dans les webhooks.
webhook_urlnontexte (URL)HTTPS, nom de domaine public.

Un fichier par requête, un devis par fichier (un PDF qui en contient plusieurs est refusé, voir Erreurs) : PDF, JPEG et PNG, 4 Mo au plus, 15 pages au plus pour un PDF. Le type est lu dans le contenu du fichier, pas dans son nom. Aucun crédit n'est débité tant que le fichier n'est pas valide.

Idempotency-Key protège d'un double envoi (réseau coupé, nouvel essai) : rejouer la même clé rend l'analyse déjà créée, sans nouveau débit. Renvoyer un fichier identique, déjà prêt ou en cours d'analyse, rend aussi l'analyse existante (réponse 200, "existante": true), sans débit.

Exemple
curl -X POST "https://www.verifiermondevis.fr/api/v1/analyses" \
  -H "Authorization: Bearer $VMD_API_KEY" \
  -H "Idempotency-Key: dossier-2026-0142" \
  -F "file=@devis.pdf" \
  -F "external_ref=dossier-2026-0142" \
  -F "webhook_url=https://example.com/webhooks/verifiermondevis"

Réponses

CodeDescription
200Même Idempotency-Key, ou même fichier déjà prêt ou en cours : l'analyse existante, sans débit.
202Analyse créée. L'en-tête VMD-Credits-Restants donne le solde.
400Corps illisible : multipart/form-data attendu, avec un champ « file ».
401Clé absente, invalide ou révoquée.
402Crédits épuisés : aucune analyse n'est créée. error.achat_url mène à la page d'achat de crédits.
403Compte suspendu.
409Une requête avec la même Idempotency-Key est en cours.
413Fichier de plus de 4 Mo.
415Format non accepté.
422Requête invalide : champ manquant ou mal formé, PDF trop long. Un PDF qui contient plusieurs devis est refusé avec error.type « plusieurs_devis » et error.devis (pages de début et de fin de chaque devis, numéro s'il est lu) : envoyez-les un par un. Aucune analyse n'est créée, aucun crédit n'est consommé.
429Débit dépassé (en-tête Retry-After).
500Erreur interne.
Réponse 202
VMD-Credits-Restants: 2
Location: /api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64

{
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64",
  "status": "queued"
}

GET /analyses/{id} : Lire une analyse

Adresse : https://www.verifiermondevis.fr/api/v1/analyses/{id}

Paramètres

NomOùObligatoireTypeDescription
idcheminouitexte (UUID)L'identifiant rendu au dépôt (id).

Sans webhook, relisez l'analyse jusqu'à un statut final (ready, rejected ou failed). Espacez les lectures de quelques secondes : elles ne consomment pas de crédit, mais un webhook vous évite d'interroger pour rien.

Exemple
curl "https://www.verifiermondevis.fr/api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64" \
  -H "Authorization: Bearer $VMD_API_KEY"

Réponses

CodeDescription
200L'analyse. Le verdict n'est présent que si status vaut ready.
401Clé absente, invalide ou révoquée.
404Analyse introuvable.
500Erreur interne.
Réponse 200 (exemple fictif : devis et entreprise inventés, SIRET invalide à dessein)
{
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64",
  "objet": "analyse",
  "contrat": "v1",
  "status": "ready",
  "external_ref": "dossier-2026-0142",
  "created_at": "2026-11-04T09:12:31.204Z",
  "completed_at": "2026-11-04T09:14:02.517Z",
  "engine_version": "1.3.0-refonte",
  "document": {
    "nom_fichier": "devis-salle-de-bains.pdf"
  },
  "montants": {
    "total_ht": 8640,
    "total_ttc": 9504,
    "ecart_estime": 726
  },
  "verdict": {
    "decision": "negocier",
    "niveau": "orange",
    "titre": "Environ 726 € à discuter avec l'artisan.",
    "motif": "La cloison BA13 sur ossature est facturée au-dessus des prix que nous avons comparés.",
    "motifs_bloquants": []
  },
  "entreprise": {
    "nom": "ATELIER EXEMPLE RÉNOVATION",
    "siret": "83245678900017",
    "identifiee": true,
    "radiee": false,
    "procedure_collective": false,
    "anciennete_annees": 12,
    "rge": false
  },
  "verifie": [
    {
      "texte": "Établie depuis 12 ans",
      "ton": "vert"
    },
    {
      "texte": "Claire sur ses conditions de paiement",
      "ton": "vert"
    }
  ],
  "a_verifier": [
    "Faites préciser la date de début et la durée des travaux : le devis n'en dit rien."
  ],
  "leviers": [
    {
      "type": "surcout_postes",
      "objectif": "negocier",
      "niveau": "important",
      "titre": "Négociez les postes au-dessus du marché (Cloison BA13 sur ossature)",
      "detail": "Sur ce poste, l'écart avec les fourchettes du marché représente environ 726 €. Appuyez-vous dessus pour demander un alignement, ligne par ligne."
    },
    {
      "type": "assurance",
      "objectif": "securiser",
      "niveau": "bonus",
      "titre": "Demandez l'attestation d'assurance décennale et RC Pro",
      "detail": "L'attestation à jour se demande par simple mail : c'est une formalité pour un artisan assuré, et une protection indispensable pour vous."
    }
  ],
  "message_artisan": "Bonjour,\n\nMerci pour votre devis. Avant de le signer, j'aurais quelques questions :\n\n1. Pouvez-vous revoir le prix des postes suivants : Cloison BA13 sur ossature ? Ils dépassent les fourchettes du marché que j'ai consultées.\n2. Pouvez-vous m'indiquer la date de début des travaux et leur durée, et les faire figurer sur le devis ?\n3. Pouvez-vous me transmettre vos attestations d'assurance décennale et RC Pro à jour ?\n\nBien cordialement,",
  "revue": {
    "statut": "automatique",
    "relue_le": null,
    "message_expert": null,
    "explication": "Aucune relecture n'est prévue pour cette analyse : rien d'autre n'est à attendre."
  },
  "limites": {
    "prix_verifies": true,
    "cas_particulier": null
  },
  "refus": null,
  "url": "https://www.verifiermondevis.fr/analyse/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64"
}

GET /analyses : Lister les analyses du compte

Adresse : https://www.verifiermondevis.fr/api/v1/analyses

Paramètres

NomOùObligatoireTypeDescription
limitrequêtenonentier, de 1 à 100, 20 par défautNombre d'analyses par page.
cursorrequêtenontexteLe next_cursor de la page précédente, tel quel.
en_revuerequêtenonune valeur parmi truetrue : seulement les analyses prêtes dont la relecture par un expert n'est pas terminée. Pour suivre les relectures sans webhook.

Les analyses du compte, des plus récentes aux plus anciennes. Pour la page suivante, renvoyez next_cursor tel quel dans cursor ; il vaut null sur la dernière page.

Exemple
curl "https://www.verifiermondevis.fr/api/v1/analyses?limit=20" \
  -H "Authorization: Bearer $VMD_API_KEY"

# Page suivante
curl "https://www.verifiermondevis.fr/api/v1/analyses?limit=20&cursor=VALEUR_DE_NEXT_CURSOR" \
  -H "Authorization: Bearer $VMD_API_KEY"

Réponses

CodeDescription
200Une page.
401Clé absente, invalide ou révoquée.
422cursor illisible, ou en_revue autre que true.
500Erreur interne.
Réponse 200
{
  "data": [
    {
      "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64",
      "status": "ready",
      "external_ref": "dossier-2026-0142",
      "created_at": "2026-11-04T09:12:31.204Z",
      "completed_at": "2026-11-04T09:14:02.517Z",
      "url": "https://www.verifiermondevis.fr/api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64"
    }
  ],
  "next_cursor": null
}

DELETE /analyses/{id} : Effacer une analyse et son document

Adresse : https://www.verifiermondevis.fr/api/v1/analyses/{id}

Paramètres

NomOùObligatoireTypeDescription
idcheminouitexte (UUID)L'identifiant rendu au dépôt (id).

Efface l'analyse et le fichier du devis. L'effacement est définitif et ne rend pas le crédit. Une analyse en cours ne s'efface pas : attendez son statut final.

Exemple
curl -X DELETE "https://www.verifiermondevis.fr/api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64" \
  -H "Authorization: Bearer $VMD_API_KEY"

Réponses

CodeDescription
204Effacée.
401Clé absente, invalide ou révoquée.
404Analyse introuvable.
409Analyse en cours.
500Erreur interne.

Statuts

Une analyse passe par queued puis processing, et finit à ready, rejected ou failed. Les statuts finaux ne changent plus ; une analyse prête peut encore être mise à jour (voir Revue humaine).

StatutSignification
queuedReçue, en attente de traitement.
processingEn cours d'analyse : lecture du devis, vérifications, verdict.
readyPrête : le verdict et le détail sont présents. Le crédit est consommé. Si revue.statut vaut en_revue, ce verdict est provisoire : la version relue par un expert arrive à la même adresse sous 24 h ouvrées (voir Revue humaine).
rejectedRefusée : le document n'est pas un devis de travaux (facture, document hors sujet). Le motif est dans refus.motif. Le crédit est rendu, 5 fois par 24 h au plus.
failedEn échec de notre côté. Le crédit est rendu, 20 fois par 24 h au plus. Vous pouvez renvoyer le fichier.

Champs de l'analyse

La réponse de GET /analyses/{id}. Tous les champs sont toujours présents ; ceux du verdict valent null ou une liste vide tant que le statut ne vaut pas ready. Des champs peuvent s'ajouter au contrat v1 : ignorez ceux que vous ne connaissez pas.

ChampTypeDescription
idtexte (UUID)Identifiant de l'analyse. À garder pour la relire, l'effacer et rapprocher les webhooks.
objettoujours analyseToujours analyse.
contrattoujours v1Version du contrat de réponse, v1.
statusune valeur parmi queued, processing, ready, rejected, failedqueued, processing, puis ready, rejected (facture ou document hors sujet) ou failed.
external_reftexte, ou nullVotre référence, telle qu'envoyée.
created_attexteISO 8601.
completed_attexte, ou nullISO 8601, quand l'analyse est prête, refusée ou en échec.
engine_versiontexte, ou nullVersion du moteur d'analyse, quand le statut vaut ready.
documentobjetLe fichier envoyé.
document.nom_fichiertexteNom du fichier, tel qu'envoyé.
montantsobjetMontants lus sur le devis, en euros.
montants.total_htnombre, ou nullTotal hors taxes lu sur le devis. null s'il n'a pas pu être lu.
montants.total_ttcnombre, ou nullTotal toutes taxes comprises lu sur le devis. null s'il n'a pas pu être lu.
montants.ecart_estimenombre, ou nullÉcart HT en euros, rattaché à des postes nommés. null s'il n'y en a pas, ou tant qu'un expert n'a pas tranché.
verdictobjet, ou nullLa décision. null tant que le statut ne vaut pas ready.
verdict.decisionune valeur parmi signer, negocier, ne_pas_signerCe que nous conseillons : signer, négocier, ne pas signer en l'état.
verdict.niveauune valeur parmi vert, orange, rougeLa couleur de la décision sur la page de l'analyse.
verdict.titretexteLe titre de la décision, tel que la page l'affiche.
verdict.motiftexte, ou nullLa raison principale, en une phrase. null quand des motifs bloquants priment.
verdict.motifs_bloquantsliste (texte)Les faits qui interdisent de signer en l'état (entreprise radiée, clause illégale, par exemple). Vide sinon.
entrepriseobjet, ou nullL'entreprise qui a émis le devis. null tant que le statut ne vaut pas ready.
entreprise.nomtexte, ou nullRaison sociale au registre, sinon le nom lu sur le devis.
entreprise.sirettexte, ou nullSIRET au registre, sinon celui lu sur le devis.
entreprise.identifieebooléenRetrouvée au registre des entreprises.
entreprise.radieebooléen, ou nulltrue si l'entreprise est radiée. null si nous ne le savons pas.
entreprise.procedure_collectivebooléen, ou nulltrue en cas de procédure collective (redressement, liquidation). null si nous ne le savons pas.
entreprise.anciennete_anneesnombre, ou nullAncienneté de l'entreprise en années, d'après le registre.
entreprise.rgebooléen, ou nulltrue si une certification RGE a été trouvée.
verifieliste d'objetsCe que nous avons vérifié.
verifie[].textetexteLe point vérifié, en une phrase.
verifie[].tonune valeur parmi vert, grisvert : un argument en faveur de l'entreprise. gris : un fait qui ne prouve que le minimum légal.
a_verifierliste (texte)Ce que le client doit vérifier avant de signer.
leviersliste d'objetsLes leviers de négociation ou de protection, du plus puissant au moins puissant.
leviers[].typetexte, ou nullIdentifiant stable du levier (par exemple acompte, surcout_postes, assurance), pour vos propres règles.
leviers[].objectifune valeur parmi negocier, securiser, ou nullNégocier le prix ou les conditions, ou sécuriser (une protection, pas une baisse de prix).
leviers[].niveauune valeur parmi puissant, important, bonus, ou nullForce du levier.
leviers[].titretexteLe conseil, à l'impératif.
leviers[].detailtexte, ou nullLe pourquoi, chiffré quand c'est possible.
message_artisantexte, ou nullUn message prêt à envoyer à l'artisan.
revueobjetLa relecture par un expert (voir Revue humaine).
revue.statutune valeur parmi automatique, en_revue, validee, corrigeeautomatique : aucune relecture, la réponse est définitive. en_revue : un expert relit l'analyse, le verdict est provisoire et une version relue suivra. validee (verdict maintenu) ou corrigee (verdict, montant ou conseils corrigés) : relecture terminée.
revue.relue_letexte, ou nullISO 8601, quand un expert a terminé la relecture. null sinon.
revue.message_experttexte, ou nullLe message de l'expert, quand il en a écrit un.
revue.explicationtexte, ou nullCe qui reste à venir pour cette analyse, en une phrase à lire ou à afficher. null tant que le statut ne vaut pas ready.
limitesobjet, ou nullCe que l'analyse n'a pas pu faire. null tant que le statut ne vaut pas ready.
limites.prix_verifiesbooléenPlus de la moitié du montant a été comparée à nos références.
limites.cas_particulierune valeur parmi devis_etranger, estimation_courtier, devis_incomplet, hors_perimetre, prestation_intellectuelle, ou nullUn cas où les prix ne sont pas comparés. null sinon.
refusobjet, ou nullPrésent quand le statut vaut rejected.
refus.motiftexteLe type de document reconnu (par exemple facture), sinon autre.
urltexteLa page de l'analyse, pour le titulaire du compte.

Erreurs

Toute erreur a la même forme : error.type (stable, à tester dans votre code) et error.message (en français, à afficher ou à journaliser). Certaines ajoutent des détails.

Exemple de réponse 402
{
  "error": {
    "type": "credits_epuises",
    "message": "Crédits épuisés : aucune analyse n'a été créée.",
    "solde": 0,
    "achat_url": "https://www.verifiermondevis.fr/developpeurs/compte"
  }
}

Types d'erreur

TypeSignification
unauthorizedClé absente, mal formée, inconnue ou révoquée.
invalid_requestRequête invalide : corps qui n'est pas du multipart/form-data, champ manquant ou trop long, fichier vide, PDF de plus de 15 pages, webhook_url refusée, cursor illisible. Le message dit lequel.
not_foundAnalyse introuvable, ou analyse d'un autre compte.
conflictRequête concurrente avec la même Idempotency-Key, ou effacement d'une analyse en cours.
payload_too_largeFichier de plus de 4 Mo.
unsupported_media_typeFormat non accepté (formats acceptés : PDF, JPEG et PNG).
rate_limitedDébit dépassé. Réessayez après le délai donné par l'en-tête Retry-After (en secondes).
credits_epuisesPlus de crédit : aucune analyse n'est créée. La réponse porte solde et achat_url.
compte_geleCompte API suspendu. Écrivez-nous.
plusieurs_devisLe PDF contient plusieurs devis : envoyez-les un par un. error.devis donne, pour chacun, ses pages de début et de fin et son numéro s'il est lu. Aucune analyse n'est créée, aucun crédit n'est consommé.
internal_errorErreur de notre côté. Réessayez : avec la même Idempotency-Key, sans risque de double analyse.

Codes par route

RouteCodeSignification
POST /analyses400Corps illisible : multipart/form-data attendu, avec un champ « file ».
POST /analyses401Clé absente, invalide ou révoquée.
POST /analyses402Crédits épuisés : aucune analyse n'est créée. error.achat_url mène à la page d'achat de crédits.
POST /analyses403Compte suspendu.
POST /analyses409Une requête avec la même Idempotency-Key est en cours.
POST /analyses413Fichier de plus de 4 Mo.
POST /analyses415Format non accepté.
POST /analyses422Requête invalide : champ manquant ou mal formé, PDF trop long. Un PDF qui contient plusieurs devis est refusé avec error.type « plusieurs_devis » et error.devis (pages de début et de fin de chaque devis, numéro s'il est lu) : envoyez-les un par un. Aucune analyse n'est créée, aucun crédit n'est consommé.
POST /analyses429Débit dépassé (en-tête Retry-After).
POST /analyses500Erreur interne.
GET /analyses/{id}401Clé absente, invalide ou révoquée.
GET /analyses/{id}404Analyse introuvable.
GET /analyses/{id}500Erreur interne.
GET /analyses401Clé absente, invalide ou révoquée.
GET /analyses422cursor illisible, ou en_revue autre que true.
GET /analyses500Erreur interne.
DELETE /analyses/{id}401Clé absente, invalide ou révoquée.
DELETE /analyses/{id}404Analyse introuvable.
DELETE /analyses/{id}409Analyse en cours.
DELETE /analyses/{id}500Erreur interne.

Webhooks

Donnez une webhook_url au dépôt du devis : nous y envoyons un POST signé à chaque événement de cette analyse, en général dans la minute.

ÉvénementQuand
analysis.readyL'analyse est prête.
analysis.rejectedLe document a été refusé.
analysis.failedL'analyse a échoué.
analysis.updatedUne analyse déjà prête a changé, le plus souvent parce qu'un expert a terminé sa relecture (revue.statut passe à validee ou corrigee). Relisez-la : la nouvelle version remplace l'ancienne.

Le corps est léger : le détail se lit par GET /analyses/{id}, ce qui évite de transporter des données personnelles et de recevoir un état périmé.

Corps
{
  "type": "analysis.ready",
  "created_at": "2026-11-04T09:14:02.517Z",
  "data": {
    "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64",
    "status": "ready",
    "external_ref": "dossier-2026-0142"
  }
}

Votre réponse

CodeEffet
200Toute réponse 2xx acquitte l'événement ; sinon 6 essais, de 1 min à 12 h.
  • Répondez en moins de 10 s. Un délai dépassé, une erreur réseau, une redirection ou un code hors 2xx comptent comme un échec.
  • 6 essais en tout : le premier, puis après 1 min, 5 min, 30 min, 2 h et 12 h. Au-delà, l'événement est abandonné ; l'analyse reste lisible par GET.
  • webhook-id est le même à chaque essai d'un même événement : servez-vous-en pour ne traiter un événement qu'une fois.
  • webhook_url : HTTPS, port 443, nom de domaine public (pas d'adresse IP, pas d'identifiants dans l'adresse).

Vérifier la signature

Chaque envoi est signé au format Standard Webhooks, avec le secret de votre compte (whsec_…, affiché sur demande dans votre espace développeur). Trois en-têtes : webhook-id, webhook-timestamp (secondes depuis 1970) et webhook-signature. La signature vaut v1, suivi du HMAC-SHA256, en base64, de webhook-id.webhook-timestamp.corps, calculé avec la clé obtenue en décodant en base64 ce qui suit whsec_.

Calculez la signature sur le corps BRUT reçu, jamais sur un JSON relu puis réécrit : un seul espace de différence et elle ne correspond plus. Rejetez un horodatage trop ancien : il protège d'un envoi rejoué.

verifier-webhook.js (Node 18 ou plus, sans dépendance)
import { createHmac, timingSafeEqual } from "node:crypto";

// Écart toléré entre l'horodatage du webhook et votre horloge.
const TOLERANCE_SECONDES = 5 * 60;

// corpsBrut : le corps reçu, tel quel (chaîne), avant tout JSON.parse.
// entetes : les en-têtes de la requête, noms en minuscules.
// secret : votre secret de signature (whsec_…).
export function verifierWebhook(corpsBrut, entetes, secret) {
  const id = entetes["webhook-id"];
  const horodatage = entetes["webhook-timestamp"];
  const signatures = entetes["webhook-signature"];
  if (!id || !horodatage || !signatures) return false;

  const ecart = Math.abs(Date.now() / 1000 - Number(horodatage));
  if (!(ecart <= TOLERANCE_SECONDES)) return false;

  const cle = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const attendue = createHmac("sha256", cle)
    .update(`${id}.${horodatage}.${corpsBrut}`)
    .digest();

  return signatures.split(" ").some((signature) => {
    const [version, valeur] = signature.split(",");
    if (version !== "v1" || !valeur) return false;
    const recue = Buffer.from(valeur, "base64");
    return recue.length === attendue.length && timingSafeEqual(recue, attendue);
  });
}
Avec Express
import express from "express";
import { verifierWebhook } from "./verifier-webhook.js";

const app = express();

// Le corps BRUT est indispensable : la signature porte sur les octets reçus.
app.post("/webhooks/verifiermondevis", express.raw({ type: "application/json" }), (req, res) => {
  const corps = req.body.toString("utf8");
  if (!verifierWebhook(corps, req.headers, process.env.VMD_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const evenement = JSON.parse(corps);
  // webhook-id ne change pas d'un essai à l'autre : ignorez un id déjà traité.
  res.sendStatus(204);
  // Puis lisez l'analyse : GET /api/v1/analyses/{evenement.data.id}
});

Les bibliothèques Standard Webhooks (standardwebhooks sur npm, PyPI et ailleurs) font la même vérification avec votre secret.

Revue humaine

Une partie des analyses est relue par un expert, comme sur le site : celles qui présentent un risque important (verdict défavorable, écart de prix élevé, cas particulier). Vous n'attendez pas l'expert pour avoir un verdict : l'analyse passe à ready tout de suite. Elle se fait en deux temps.

1. Tout de suite : un verdict provisoire

  • status vaut ready et revue.statut vaut en_revue.
  • verdict est présent, mais provisoire. montants.ecart_estime vaut null et le titre ne cite aucun montant : l'écart de prix attend l'expert.
  • revue.explication dit en une phrase ce qui reste à venir et où le trouver. Affichez-la à votre utilisateur, ou journalisez-la.
  • Le crédit est consommé à ce moment-là. La relecture ne coûte rien de plus.
Extrait d'une réponse pendant la relecture
{
  "status": "ready",
  "montants": {
    "total_ht": 10527.97,
    "total_ttc": 12633.56,
    "ecart_estime": null
  },
  "revue": {
    "statut": "en_revue",
    "relue_le": null,
    "message_expert": null,
    "explication": "Un expert relit cette analyse. Ce verdict est provisoire et l'écart de prix n'est pas encore donné. La version relue remplacera celle-ci à la même adresse, sous 24 h ouvrées : relisez GET https://www.verifiermondevis.fr/api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64, ou recevez l'événement analysis.updated si vous avez donné une webhook_url. Sans webhook_url, le titulaire du compte est en général prévenu aussi par e-mail. Les analyses encore en relecture : GET https://www.verifiermondevis.fr/api/v1/analyses?en_revue=true."
  }
}

2. Sous 24 h ouvrées : la version relue, à la même adresse

  • L'expert tranche sous 24 h ouvrées. La version relue remplace la précédente : même id, même GET /analyses/{id}, status toujours ready.
  • revue.statut passe à validee (verdict maintenu) ou corrigee (verdict, montant ou conseils corrigés), et revue.relue_le donne la date.
  • montants.ecart_estime est rempli s'il y a un écart de prix, et revue.message_expert porte le message de l'expert quand il en a écrit un.

Comment savoir que la version relue est arrivée

Votre casCe qui se passe
Vous avez donné une webhook_url au dépôtVous recevez l'événement analysis.updated. Relisez l'analyse par GET /analyses/{id}.
Pas de webhook, vous interrogez l'APIGET /analyses?en_revue=true liste les analyses prêtes dont la relecture n'est pas terminée. Quand une analyse en disparaît, relisez-la par GET /analyses/{id} : la version relue y est (vérifiez revue.statut). Une interrogation par heure suffit.
Pas de webhook, vous testez à la mainLe titulaire du compte reçoit en général un e-mail « Analyse relue par un expert » avec le lien vers l'analyse. Cet e-mail n'est pas envoyé quand l'analyse a une webhook_url.
Suivre les relectures sans webhook
curl "https://www.verifiermondevis.fr/api/v1/analyses?en_revue=true" \
  -H "Authorization: Bearer $VMD_API_KEY"
# Chaque analyse listée est encore en relecture.
# Une analyse qui n'y figure plus : relisez-la par GET https://www.verifiermondevis.fr/api/v1/analyses/{id}

Quand revue.statut vaut automatique, aucune relecture n'est prévue : la première réponse est la seule, rien d'autre n'est à attendre.

Depuis Claude Code ou Codex

Le serveur MCP https://www.verifiermondevis.fr/mcp donne les mêmes analyses que l'API, avec la même clé et les mêmes crédits. Dans Claude Code ou Codex, écrivez par exemple « analyse ce devis ./devis.pdf » : l'agent envoie le fichier, lance l'analyse, attend le résultat et vous le recopie. Sans clé, depuis Claude Code, Claude ou ChatGPT : voir Connexion sans clé.

Claude Code : le plugin

Dans un terminal, avant de lancer Claude Code
export VMD_API_KEY="vmd_VOTRE_CLE"
Puis dans Claude Code
/plugin marketplace add messagingme/verifiermondevis-plugin
/plugin install verifiermondevis@verifiermondevis

Sans le plugin, on ajoute seulement le serveur : claude mcp add --transport http verifiermondevis https://www.verifiermondevis.fr/mcp --header "Authorization: Bearer $VMD_API_KEY".

Codex

~/.codex/config.toml
[mcp_servers.verifiermondevis]
url = "https://www.verifiermondevis.fr/mcp"
bearer_token_env_var = "VMD_API_KEY"

Les outils

OutilRôle
prepare_uploadPremière étape pour analyser un devis (PDF, JPEG ou PNG, 4 Mo au plus) : rend une adresse d'envoi, valable 10 minutes et pour un seul fichier, et la commande curl qui y dépose le fichier. Lancez cette commande (curl.exe sous PowerShell), puis appelez analyze_quote avec l'upload_id rendu. Ne débite aucun crédit.
analyze_quoteLance l'analyse du devis envoyé après prepare_upload. Débite un crédit. Rappeler cet outil avec le même upload_id ne débite pas une seconde fois. L'analyse prend en général 1 à 3 minutes : suivez-la ensuite avec get_analysis.
get_analysisLe statut d'une analyse, puis son résultat : verdict, montants, écart sur les prix, entreprise, conseils, message à envoyer à l'artisan et lien de la page. Recopiez ce texte à l'utilisateur en entier, sans le résumer. Le JSON complet est celui de GET /api/v1/analyses/{id}.
list_analysesLes analyses du compte, des plus récentes aux plus anciennes. en_revue = true ne garde que celles qu'un expert relit encore (leur version relue arrive sous 24 h ouvrées).
  • Le fichier ne passe pas par la conversation : prepare_upload donne une adresse d'envoi, valable 10 minutes et pour un seul fichier, où l'agent le dépose avec curl. La clé n'apparaît dans aucune commande.
  • Une analyse lancée par analyze_quote débite un crédit, exactement comme POST /analyses, et suit les mêmes règles : mêmes formats, même taille, même refus d'un PDF de plusieurs devis. La relancer avec le même upload_id ne débite pas une seconde fois.
  • get_analysis rend le résultat rédigé, à recopier tel quel (verdict, montants, conseils, message à l'artisan, relecture en cours). Le JSON complet reste celui de GET /analyses/{id}.

Connexion sans clé (Claude, Claude Code, ChatGPT)

Un assistant peut aussi se brancher sur le serveur MCP https://www.verifiermondevis.fr/mcp sans clé d'API. Vous ajoutez cette adresse dans l'assistant, une fenêtre s'ouvre sur verifiermondevis.fr, vous vous connectez avec votre compte (ou vous le créez) et vous autorisez l'application. Les outils sont les mêmes qu'avec une clé.

Claude Code

Dans un terminal
claude mcp add --transport http vmd https://www.verifiermondevis.fr/mcp

Puis, dans Claude Code, tapez /mcp, choisissez vmd et lancez la connexion : la page d'autorisation s'ouvre dans votre navigateur. Si le plugin VerifierMonDevis est installé, ce serveur ajouté à la main prend la place du sien (même adresse) et ses compétences restent disponibles.

Claude (claude.ai et l'application)

Dans les paramètres, rubrique Connecteurs, ajoutez un connecteur personnalisé avec l'adresse https://www.verifiermondevis.fr/mcp, puis connectez-vous.

ChatGPT

En mode développeur, ajoutez un connecteur avec l'adresse https://www.verifiermondevis.fr/mcp et l'authentification OAuth, puis connectez-vous.

Ce que vous autorisez

Pour autoriser une application, votre compte doit être confirmé (lien reçu par e-mail) et les conditions d'utilisation de l'API acceptées : la page d'autorisation vous les fait accepter si ce n'est pas déjà fait. La page dit quelle application demande l'accès et ce qu'elle pourra faire.

DroitCe que l'application peut faireOutils
mcp:readLire vos analyses : la liste, le verdict, le détail.list_analyses, get_analysis
mcp:writeEnvoyer un devis et lancer une analyse, avec vos crédits.prepare_upload, analyze_quote
  • L'application n'a accès à rien d'autre : ni à votre compte sur le site, ni à vos chantiers, ni à vos clés. Ce qu'elle reçoit ne vaut que pour le serveur MCP.
  • Elle reste connectée sans vous redemander quoi que ce soit : son accès, valable 1 h, se renouvelle de lui-même. Si elle ne sert pas pendant 30 jours, ou au bout de 90 jours, elle vous demandera de vous reconnecter.

Crédits

  • Une analyse lancée par une application connectée débite un crédit de votre compte, exactement comme avec une clé : même solde, mêmes règles de remboursement (voir Crédits et facturation).
  • Votre première autorisation vous offre 3 analyses si votre compte n'en a jamais reçu : c'est la même offre que la première clé, une seule fois par compte.
  • Sans crédit, analyze_quote le dit et donne le lien d'achat ; aucune analyse n'est créée.

Retirer l'accès

Sur votre espace développeur, rubrique Applications autorisées, cliquez sur Révoquer : l'appel suivant de l'application est refusé et elle vous demande de vous reconnecter. Vos analyses restent.

Crédits et facturation

  • 3 analyses sont offertes à la création de votre première clé ou à la première autorisation d'une application (voir Connexion sans clé), une seule fois par compte.
  • Un crédit est réservé au dépôt (l'en-tête VMD-Credits-Restants donne le solde après réservation) et consommé quand l'analyse est prête.
  • Document refusé (rejected) : le crédit est rendu, 5 fois par 24 h au plus. Analyse en échec (failed) : rendu aussi, 20 fois par 24 h au plus.
  • Pas de débit si vous rejouez la même Idempotency-Key, ni si vous renvoyez un fichier identique déjà prêt ou en cours d'analyse : l'analyse existante est rendue.
  • Effacer une analyse ne rend pas son crédit. Sans crédit, le dépôt répond 402 et aucune analyse n'est créée.
PaquetPrix hors taxesPrix par analyse
50 analyses75 € HT1,50 € HT
250 analyses300 € HT1,20 € HT

Les crédits s'achètent par carte sur votre espace développeur, avec une facture à votre entreprise. Achat réservé aux professionnels : voir les conditions de vente.

Limites

LimiteValeur
Envois par minute et par compte, refusés compris10
Analyses en cours en même temps, par compte5
Taille d'un fichier4 Mo au plus
Pages d'un PDF15 au plus
Formats acceptésPDF, JPEG et PNG
Analyses par page de liste100 au plus, 20 par défaut

Au-delà du débit, la réponse est 429 avec l'en-tête Retry-After : attendez ce délai avant de renvoyer.