# Documentation de l'API VerifierMonDevis

Version web : https://www.verifiermondevis.fr/developpeurs/documentation

- Présentation
- Démarrage rapide
- Authentification
- `POST /analyses` : Déposer un devis
- `GET /analyses/{id}` : Lire une analyse
- `GET /analyses` : Lister les analyses du compte
- `DELETE /analyses/{id}` : Effacer une analyse et son document
- Statuts
- Champs de l'analyse
- Erreurs
- Webhooks
- Revue humaine
- Depuis Claude Code ou Codex
- Connexion sans clé (Claude, Claude Code, ChatGPT)
- Crédits et facturation
- Limites

## 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](https://www.verifiermondevis.fr/api/v1/openapi.json). Cette documentation existe aussi en Markdown : [https://www.verifiermondevis.fr/developpeurs/documentation.md](https://www.verifiermondevis.fr/developpeurs/documentation.md).

## Démarrage rapide

- Créez votre compte sur [verifiermondevis.fr](https://www.verifiermondevis.fr/inscription?returnTo=/developpeurs/compte) et confirmez votre adresse e-mail (lien reçu à l'inscription).
- Sur [votre espace développeur](https://www.verifiermondevis.fr/developpeurs/compte), 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` :

```bash
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_`.

```http
Authorization: Bearer vmd_VOTRE_CLE
```

- Créez vos clés sur [votre espace développeur](https://www.verifiermondevis.fr/developpeurs/compte), 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.

Exemple :

```bash
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. |

Réponse 202 :

```http
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.

Exemple :

```bash
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. |

Réponse 200 (exemple fictif : devis et entreprise inventés, SIRET invalide à dessein) :

```json
{
  "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.

Exemple :

```bash
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. |

Réponse 200 :

```json
{
  "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.

Exemple :

```bash
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.

Exemple de réponse 402 :

```json
{
  "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é.

Corps :

```json
{
  "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-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](https://www.standardwebhooks.com/), avec le secret de votre compte (`whsec_…`, affiché sur demande dans [votre espace développeur](https://www.verifiermondevis.fr/developpeurs/compte)). 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) :

```js
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 :

```js
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 :

```json
{
  "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 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`. |

Suivre les relectures sans webhook :

```bash
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 :

```bash
export VMD_API_KEY="vmd_VOTRE_CLE"
```

Puis dans Claude Code :

```text
/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 :

```toml
[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_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 :

```bash
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](https://www.verifiermondevis.fr/conditions-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_quote` le dit et donne le lien d'achat ; aucune analyse n'est créée.

### Retirer l'accès

Sur [votre espace développeur](https://www.verifiermondevis.fr/developpeurs/compte), 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.

| 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](https://www.verifiermondevis.fr/developpeurs/compte), avec une facture à votre entreprise. Achat réservé aux professionnels : voir les [conditions de vente](https://www.verifiermondevis.fr/conditions-api).

## 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.
