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
202avec sonid), puis vous lisez l'analyse quand son statut vautready, 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
| Nom | Où | Obligatoire | Type | Description |
|---|---|---|---|---|
Idempotency-Key | en-tête | non | texte, 200 caractères au plus | Rejouer 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)
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
file | oui | fichier | PDF, JPEG ou PNG, 4 Mo au plus, 15 pages au plus. |
external_ref | non | texte, 200 caractères au plus | Votre référence (un numéro de dossier, par exemple), rendue telle quelle dans l'analyse et dans les webhooks. |
webhook_url | non | texte (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.
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
| Code | Description |
|---|---|
200 | Même Idempotency-Key, ou même fichier déjà prêt ou en cours : l'analyse existante, sans débit. |
202 | Analyse créée. L'en-tête VMD-Credits-Restants donne le solde. |
400 | Corps illisible : multipart/form-data attendu, avec un champ « file ». |
401 | Clé absente, invalide ou révoquée. |
402 | Crédits épuisés : aucune analyse n'est créée. error.achat_url mène à la page d'achat de crédits. |
403 | Compte suspendu. |
409 | Une requête avec la même Idempotency-Key est en cours. |
413 | Fichier de plus de 4 Mo. |
415 | Format non accepté. |
422 | Requê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é. |
429 | Débit dépassé (en-tête Retry-After). |
500 | Erreur interne. |
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
| Nom | Où | Obligatoire | Type | Description |
|---|---|---|---|---|
id | chemin | oui | texte (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.
curl "https://www.verifiermondevis.fr/api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64" \
-H "Authorization: Bearer $VMD_API_KEY"Réponses
| Code | Description |
|---|---|
200 | L'analyse. Le verdict n'est présent que si status vaut ready. |
401 | Clé absente, invalide ou révoquée. |
404 | Analyse introuvable. |
500 | Erreur interne. |
{
"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
| Nom | Où | Obligatoire | Type | Description |
|---|---|---|---|---|
limit | requête | non | entier, de 1 à 100, 20 par défaut | Nombre d'analyses par page. |
cursor | requête | non | texte | Le next_cursor de la page précédente, tel quel. |
en_revue | requête | non | une valeur parmi true | true : 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.
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
| Code | Description |
|---|---|
200 | Une page. |
401 | Clé absente, invalide ou révoquée. |
422 | cursor illisible, ou en_revue autre que true. |
500 | Erreur interne. |
{
"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
| Nom | Où | Obligatoire | Type | Description |
|---|---|---|---|---|
id | chemin | oui | texte (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.
curl -X DELETE "https://www.verifiermondevis.fr/api/v1/analyses/3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c64" \
-H "Authorization: Bearer $VMD_API_KEY"Réponses
| Code | Description |
|---|---|
204 | Effacée. |
401 | Clé absente, invalide ou révoquée. |
404 | Analyse introuvable. |
409 | Analyse en cours. |
500 | Erreur 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).
| Statut | Signification |
|---|---|
queued | Reçue, en attente de traitement. |
processing | En cours d'analyse : lecture du devis, vérifications, verdict. |
ready | Prê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). |
rejected | Refusé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. |
failed | En é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.
| Champ | Type | Description |
|---|---|---|
id | texte (UUID) | Identifiant de l'analyse. À garder pour la relire, l'effacer et rapprocher les webhooks. |
objet | toujours analyse | Toujours analyse. |
contrat | toujours v1 | Version du contrat de réponse, v1. |
status | une valeur parmi queued, processing, ready, rejected, failed | queued, processing, puis ready, rejected (facture ou document hors sujet) ou failed. |
external_ref | texte, ou null | Votre référence, telle qu'envoyée. |
created_at | texte | ISO 8601. |
completed_at | texte, ou null | ISO 8601, quand l'analyse est prête, refusée ou en échec. |
engine_version | texte, ou null | Version du moteur d'analyse, quand le statut vaut ready. |
document | objet | Le fichier envoyé. |
document.nom_fichier | texte | Nom du fichier, tel qu'envoyé. |
montants | objet | Montants lus sur le devis, en euros. |
montants.total_ht | nombre, ou null | Total hors taxes lu sur le devis. null s'il n'a pas pu être lu. |
montants.total_ttc | nombre, ou null | Total toutes taxes comprises lu sur le devis. null s'il n'a pas pu être lu. |
montants.ecart_estime | nombre, 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é. |
verdict | objet, ou null | La décision. null tant que le statut ne vaut pas ready. |
verdict.decision | une valeur parmi signer, negocier, ne_pas_signer | Ce que nous conseillons : signer, négocier, ne pas signer en l'état. |
verdict.niveau | une valeur parmi vert, orange, rouge | La couleur de la décision sur la page de l'analyse. |
verdict.titre | texte | Le titre de la décision, tel que la page l'affiche. |
verdict.motif | texte, ou null | La raison principale, en une phrase. null quand des motifs bloquants priment. |
verdict.motifs_bloquants | liste (texte) | Les faits qui interdisent de signer en l'état (entreprise radiée, clause illégale, par exemple). Vide sinon. |
entreprise | objet, ou null | L'entreprise qui a émis le devis. null tant que le statut ne vaut pas ready. |
entreprise.nom | texte, ou null | Raison sociale au registre, sinon le nom lu sur le devis. |
entreprise.siret | texte, ou null | SIRET au registre, sinon celui lu sur le devis. |
entreprise.identifiee | booléen | Retrouvée au registre des entreprises. |
entreprise.radiee | booléen, ou null | true si l'entreprise est radiée. null si nous ne le savons pas. |
entreprise.procedure_collective | booléen, ou null | true en cas de procédure collective (redressement, liquidation). null si nous ne le savons pas. |
entreprise.anciennete_annees | nombre, ou null | Ancienneté de l'entreprise en années, d'après le registre. |
entreprise.rge | booléen, ou null | true si une certification RGE a été trouvée. |
verifie | liste d'objets | Ce que nous avons vérifié. |
verifie[].texte | texte | Le point vérifié, en une phrase. |
verifie[].ton | une valeur parmi vert, gris | vert : un argument en faveur de l'entreprise. gris : un fait qui ne prouve que le minimum légal. |
a_verifier | liste (texte) | Ce que le client doit vérifier avant de signer. |
leviers | liste d'objets | Les leviers de négociation ou de protection, du plus puissant au moins puissant. |
leviers[].type | texte, ou null | Identifiant stable du levier (par exemple acompte, surcout_postes, assurance), pour vos propres règles. |
leviers[].objectif | une valeur parmi negocier, securiser, ou null | Négocier le prix ou les conditions, ou sécuriser (une protection, pas une baisse de prix). |
leviers[].niveau | une valeur parmi puissant, important, bonus, ou null | Force du levier. |
leviers[].titre | texte | Le conseil, à l'impératif. |
leviers[].detail | texte, ou null | Le pourquoi, chiffré quand c'est possible. |
message_artisan | texte, ou null | Un message prêt à envoyer à l'artisan. |
revue | objet | La relecture par un expert (voir Revue humaine). |
revue.statut | une valeur parmi automatique, en_revue, validee, corrigee | automatique : 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_le | texte, ou null | ISO 8601, quand un expert a terminé la relecture. null sinon. |
revue.message_expert | texte, ou null | Le message de l'expert, quand il en a écrit un. |
revue.explication | texte, ou null | Ce qui reste à venir pour cette analyse, en une phrase à lire ou à afficher. null tant que le statut ne vaut pas ready. |
limites | objet, ou null | Ce que l'analyse n'a pas pu faire. null tant que le statut ne vaut pas ready. |
limites.prix_verifies | booléen | Plus de la moitié du montant a été comparée à nos références. |
limites.cas_particulier | une valeur parmi devis_etranger, estimation_courtier, devis_incomplet, hors_perimetre, prestation_intellectuelle, ou null | Un cas où les prix ne sont pas comparés. null sinon. |
refus | objet, ou null | Présent quand le statut vaut rejected. |
refus.motif | texte | Le type de document reconnu (par exemple facture), sinon autre. |
url | texte | La 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.
{
"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
| Type | Signification |
|---|---|
unauthorized | Clé absente, mal formée, inconnue ou révoquée. |
invalid_request | Requê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_found | Analyse introuvable, ou analyse d'un autre compte. |
conflict | Requête concurrente avec la même Idempotency-Key, ou effacement d'une analyse en cours. |
payload_too_large | Fichier de plus de 4 Mo. |
unsupported_media_type | Format non accepté (formats acceptés : PDF, JPEG et PNG). |
rate_limited | Débit dépassé. Réessayez après le délai donné par l'en-tête Retry-After (en secondes). |
credits_epuises | Plus de crédit : aucune analyse n'est créée. La réponse porte solde et achat_url. |
compte_gele | Compte API suspendu. Écrivez-nous. |
plusieurs_devis | Le 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_error | Erreur de notre côté. Réessayez : avec la même Idempotency-Key, sans risque de double analyse. |
Codes par route
| Route | Code | Signification |
|---|---|---|
POST /analyses | 400 | Corps illisible : multipart/form-data attendu, avec un champ « file ». |
POST /analyses | 401 | Clé absente, invalide ou révoquée. |
POST /analyses | 402 | Crédits épuisés : aucune analyse n'est créée. error.achat_url mène à la page d'achat de crédits. |
POST /analyses | 403 | Compte suspendu. |
POST /analyses | 409 | Une requête avec la même Idempotency-Key est en cours. |
POST /analyses | 413 | Fichier de plus de 4 Mo. |
POST /analyses | 415 | Format non accepté. |
POST /analyses | 422 | Requê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 /analyses | 429 | Débit dépassé (en-tête Retry-After). |
POST /analyses | 500 | Erreur interne. |
GET /analyses/{id} | 401 | Clé absente, invalide ou révoquée. |
GET /analyses/{id} | 404 | Analyse introuvable. |
GET /analyses/{id} | 500 | Erreur interne. |
GET /analyses | 401 | Clé absente, invalide ou révoquée. |
GET /analyses | 422 | cursor illisible, ou en_revue autre que true. |
GET /analyses | 500 | Erreur interne. |
DELETE /analyses/{id} | 401 | Clé absente, invalide ou révoquée. |
DELETE /analyses/{id} | 404 | Analyse introuvable. |
DELETE /analyses/{id} | 409 | Analyse en cours. |
DELETE /analyses/{id} | 500 | Erreur 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énement | Quand |
|---|---|
analysis.ready | L'analyse est prête. |
analysis.rejected | Le document a été refusé. |
analysis.failed | L'analyse a échoué. |
analysis.updated | Une 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é.
{
"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
| Code | Effet |
|---|---|
200 | Toute 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-idest 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é.
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);
});
}
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
statusvautreadyetrevue.statutvauten_revue.verdictest présent, mais provisoire.montants.ecart_estimevautnullet le titre ne cite aucun montant : l'écart de prix attend l'expert.revue.explicationdit 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.
{
"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êmeGET /analyses/{id},statustoujoursready. revue.statutpasse àvalidee(verdict maintenu) oucorrigee(verdict, montant ou conseils corrigés), etrevue.relue_ledonne la date.montants.ecart_estimeest rempli s'il y a un écart de prix, etrevue.message_expertporte le message de l'expert quand il en a écrit un.
Comment savoir que la version relue est arrivée
| Votre cas | Ce qui se passe |
|---|---|
Vous avez donné une webhook_url au dépôt | Vous recevez l'événement analysis.updated. Relisez l'analyse par GET /analyses/{id}. |
| Pas de webhook, vous interrogez l'API | GET /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 main | Le 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. |
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
export VMD_API_KEY="vmd_VOTRE_CLE"/plugin marketplace add messagingme/verifiermondevis-plugin
/plugin install verifiermondevis@verifiermondevisSans 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
[mcp_servers.verifiermondevis]
url = "https://www.verifiermondevis.fr/mcp"
bearer_token_env_var = "VMD_API_KEY"Les outils
| Outil | Rôle |
|---|---|
prepare_upload | Premiè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_quote | Lance 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_analysis | Le 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_analyses | Les 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_uploaddonne une adresse d'envoi, valable 10 minutes et pour un seul fichier, où l'agent le dépose aveccurl. La clé n'apparaît dans aucune commande. - Une analyse lancée par
analyze_quotedébite un crédit, exactement commePOST /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êmeupload_idne débite pas une seconde fois. get_analysisrend le résultat rédigé, à recopier tel quel (verdict, montants, conseils, message à l'artisan, relecture en cours). Le JSON complet reste celui deGET /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
claude mcp add --transport http vmd https://www.verifiermondevis.fr/mcpPuis, 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.
| Droit | Ce que l'application peut faire | Outils |
|---|---|---|
mcp:read | Lire vos analyses : la liste, le verdict, le détail. | list_analyses, get_analysis |
mcp:write | Envoyer 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_quotele 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-Restantsdonne 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
402et aucune analyse n'est créée.
| Paquet | Prix hors taxes | Prix par analyse |
|---|---|---|
| 50 analyses | 75 € HT | 1,50 € HT |
| 250 analyses | 300 € HT | 1,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
| Limite | Valeur |
|---|---|
| Envois par minute et par compte, refusés compris | 10 |
| Analyses en cours en même temps, par compte | 5 |
| Taille d'un fichier | 4 Mo au plus |
| Pages d'un PDF | 15 au plus |
| Formats acceptés | PDF, JPEG et PNG |
| Analyses par page de liste | 100 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.