L'API de données véhicule VIN Doc
Une API REST pensée pour les développeurs, pour l'historique véhicule à l'échelle. Créez des lookups, décodez des VIN et lancez des jobs bulk via une base URL unique, avec authentification Bearer, webhooks signés et rate limits par clé.
https://api.vin-doc.com/v1Provisionner les clés API
Créez un compte et provisionnez une paire de clés depuis le dashboard : une clé sandbox pour les tests d'intégration et une clé de production. Le trafic sandbox est gratuit et ne consomme jamais de quota facturable.
Lancer votre premier appel
Passez votre token dans l'en-tête Authorization: Bearer et faites un GET /v1/vin/{vin}/decode sur la base URL https://api.vin-doc.com pour valider la connectivité avant de créer des lookups.
Traiter la réponse & les webhooks
Le décodage renvoie du JSON en synchrone ; un lookup est asynchrone, interrogez l'endpoint de statut ou enregistrez un webhook pour recevoir le payload complet dès qu'il est prêt.
Authentification
Toutes les requêtes sont authentifiées par un token Bearer dans l'en-tête Authorization, plus un en-tête X-Api-Key, en HTTPS. Les clés sont scopées (sandbox vs production), peuvent être renouvelées sans interruption et expirent 12 mois après émission.
cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY" \
https://api.vin-doc.com/v1/vin/WBA3A5G59DNP26082/decodeSécurité
Gardez les clés côté serveur. Ne les intégrez jamais dans du code client ni dans des query strings, faites transiter les appels par votre backend ou un proxy et stockez les secrets dans des variables d'environnement.
Endpoints
Cinq endpoints v1 partagent la base URL https://api.vin-doc.com et un même vocabulaire /v1/lookups. Tous échangent du JSON (Content-Type: application/json) ; les endpoints POST attendent un corps JSON et prennent en charge les clés d'idempotence.
/v1/lookupsCréer un lookup
Crée un lookup véhicule. Le traitement est asynchrone : la réponse renvoie un lookup_id préfixé lkp_ avec le statut pending, qui passe à completed (médiane ~55 s). Enregistrez un webhook pour recevoir l'événement lookup.completed.
Paramètres
| Nom | Type | Description |
|---|---|---|
| vin | string | VIN ISO 3779 de 17 caractères. Requis si license_plate est absent |
| license_plate | string | Plaque d'immatriculation. Requis si vin est absent |
| country | string | Code pays ISO 3166-1 alpha-2, par exemple FR |
| callback_url | string | URL de webhook HTTPS notifiée à la fin du lookup |
Exemple de requête
# By VIN
curl -X POST https://api.vin-doc.com/v1/lookups \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"vin": "WBA3A5G59DNP26082", "country": "FR"}'
# By license plate
curl -X POST https://api.vin-doc.com/v1/lookups \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"license_plate": "AB-123-CD", "country": "FR"}'/v1/lookups/{lookup_id}Récupérer un lookup
Renvoie l'objet lookup typé complet pour un lookup_id donné une fois terminé, incluant les données vehicle, history, inspection et emissions.
Exemple de requête
curl -X GET https://api.vin-doc.com/v1/lookups/lkp_4a91c2 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY"/v1/lookups/{lookup_id}/statusRécupérer le statut d'un lookup
Renvoie l'état courant d'un lookup asynchrone, pending, processing, completed ou failed, ainsi qu'un lien vers le résultat une fois prêt. À utiliser si vous ne vous appuyez pas sur les webhooks.
Exemple de requête
curl -X GET https://api.vin-doc.com/v1/lookups/lkp_4a91c2/status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY"/v1/lookups/batchLookups bulk
Met en file un tableau d'identifiers (VIN ou plaques) pour un traitement parallèle en une seule requête, conçu pour les flottes et les imports en masse. Chaque identifiant est facturé et suivi indépendamment ; les résultats reviennent via le webhook batch.completed.
Exemple de requête
curl -X POST https://api.vin-doc.com/v1/lookups/batch \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"identifiers": ["WBA3A5G59DNP26082", "AB-123-CD"]}'/v1/vin/{vin}/decodeDécoder un VIN
Lookup synchrone qui décode un VIN ISO 3779 en constructeur, modèle, année-modèle, usine et spécifications moteur d'origine. Idéal pour préremplir des formulaires avant de créer un lookup complet.
Exemple de requête
curl -X GET https://api.vin-doc.com/v1/vin/WBA3A5G59DNP26082/decode \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Api-Key: YOUR_API_KEY"Schéma de réponse
Un lookup terminé renvoie un objet typé identifié par lookup_id. vehicle porte les specs décodées, history agrège kilométrage, accidents, vol et titre, et inspection, emissions et meta complètent l'enregistrement.
200 OK
{
"lookup_id": "lkp_4a91c2",
"vin": "WBA3A5G59DNP26082",
"generated_at": "2026-03-12T10:04:00Z",
"vehicle": { "make": "BMW", "model": "320d", "year": 2019 },
"history": {
"mileage": { "value": 142350, "unit": "km", "consistent": true },
"accidents": { "count": 0 },
"theft": { "reported": false },
"title": "clean"
},
"inspection": { "passed": true, "date": "2025-09" },
"emissions": { "class": "Euro 6d" },
"sources": 8200,
"meta": { "country": "FR" }
}Champs de réponse
| Champ | Description |
|---|---|
lookup_id | Identifiant unique du lookup, préfixé lkp_ |
vin | Le numéro VIN qui a été interrogé |
generated_at | Horodatage ISO 8601 de génération du lookup |
vehicle | Objet véhicule décodé : make, model et year |
history.mileage | Objet kilométrage : valeur, unité et indicateur de cohérence |
history.accidents | Objet accidents : nombre signalé |
history.theft | Objet vol : booléen reported |
history.title | Statut du titre, par exemple clean |
inspection | Objet contrôle technique : booléen passed et date |
emissions | Objet émissions : class, par exemple Euro 6d |
sources | Nombre de sources de données interrogées pour ce lookup |
meta.country | Code pays ISO 3166-1 pour lequel le lookup a été lancé |
Codes d'erreur
L'API utilise des codes de statut HTTP conventionnels avec les reason phrases standard. En cas d'échec, le corps contient un objet error avec un code numérique, un message court et un detail lisible pour accélérer le débogage.
| Code | Message | Description |
|---|---|---|
| 400 | Bad Request | Le corps JSON est malformé ou un champ requis (vin ou license_plate, plus country) est manquant. |
| 401 | Unauthorized | Le token Bearer ou X-Api-Key est manquant, invalide, expiré ou a été révoqué. |
| 403 | Forbidden | La clé est valide mais ne dispose pas du scope ou de l'éligibilité de plan pour cet endpoint. |
| 404 | Not Found | La ressource référencée, lookup_id ou VIN, n'existe pas. |
| 429 | Too Many Requests | Rate limit par clé dépassé. Inspectez les en-têtes X-RateLimit et réessayez après la fenêtre de reset. |
| 500 | Internal Server Error | Une erreur inattendue est survenue en amont. Réessayez avec backoff ou contactez le support si cela persiste. |
Exemple de réponse d'erreur
{
"status": "error",
"error": {
"code": 401,
"message": "Unauthorized",
"detail": "The provided API key is invalid or has expired."
}
}Rate limiting
Le throttling est appliqué par clé API avec un algorithme de fenêtre glissante ; les plafonds évoluent avec votre plan et les clés Enterprise peuvent obtenir des limites dédiées. Des compteurs en temps réel sont renvoyés à chaque réponse.
300
Requêtes / min
50,000
Requêtes / jour
25
Concurrentes
En-têtes de rate limit
Chaque réponse porte des en-têtes pour suivre votre consommation et faire du backoff proprement avant d'atteindre un 429.
X-RateLimit-LimitNombre maximum de requêtes autorisées dans la fenêtre couranteX-RateLimit-RemainingRequêtes encore disponibles dans la fenêtre couranteX-RateLimit-ResetTimestamp Unix de réinitialisation de la fenêtreConstruisez sur l'API VIN Doc
Demandez un accès production ou échangez avec nos ingénieurs d'intégration sur le volume à l'échelle d'une flotte. Du sandbox à la production, c'est un simple changement de clé, aucune modification de code.