API d'import

Gardez votre inventaire Driv.one synchronisé avec votre DMS ou votre système de stock. Créez et mettez à jour des véhicules, envoyez des inventaires complets, gérez les photos — via une API REST versionnée limitée à votre garage.

L'API s'adresse aux vendeurs professionnels, groupes de concessionnaires, éditeurs de DMS et partenaires d'intégration. Les fiches que vous créez apparaissent sur driv.one sous votre garage, exactement comme les voitures ajoutées à la main.

Démarrage rapide

1. Créez une clé API

Connectez-vous à {link}, choisissez le garage, nommez la clé et copiez-la. La clé n'est affichée qu'une fois ; si vous la perdez, révoquez-la et créez-en une autre.

2. Testez l'authentification

Copiercurl https://api.driv.one/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

3. Créez un véhicule

Copiercurl -X POST https://api.driv.one/v1/vehicles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "STOCK-4821",
  "external_updated_at": "2026-09-05T08:30:00Z",
  "make": "Volkswagen",
  "model": "Golf",
  "year": 2022,
  "vin": "WVWZZZAUZNW123456",
  "license_plate": "1-ABC-123",
  "mileage": 41200,
  "first_registration": "2022-03-15",
  "fuel_type": "petrol",
  "gearbox_type": "dct",
  "body_type": "hatchback",
  "power_hp": 150,
  "num_doors": 5,
  "num_seats": 5,
  "color": "gray",
  "interior_material": "fabric",
  "vehicle_condition": "used",
  "asking_price": 24950,
  "is_tax_vehicle": true,
  "short_description": "Golf 1.5 TSI Life, first owner, full history",
  "seller_description": "Serviced at the dealership, two keys, winter tyres included.",
  "features": [
    "appleCarplay",
    "androidAuto",
    "adaptiveCruiseControl",
    "ledHeadlights",
    "alloyWheels"
  ],
  "parking_assist": [
    "sens_front",
    "sens_rear",
    "cam_rear"
  ],
  "image_urls": [
    "https://cdn.example-dealer.be/stock/4821/front.jpg",
    "https://cdn.example-dealer.be/stock/4821/interior.jpg"
  ]
}'

La réponse est le véhicule enregistré avec son uuid, public_url, currency et ses photos, plus un tableau warnings lorsqu'un incident non bloquant s'est produit (une photo introuvable, un modèle créé).

URL de base et versions

Copierhttps://api.driv.one/v1

La version majeure fait partie du chemin. Les changements incompatibles reçoivent une nouvelle version majeure ; /v1 conserve son comportement. Les ajouts (nouveaux champs optionnels, nouvelles valeurs d'énumération) peuvent apparaître dans v1 — lisez GET /v1/options plutôt que de figer des listes.

Les chemins sont indiqués sans barre finale ; elle est acceptée.

Authentification

Authentification par jeton Bearer avec une clé API du garage. Les clés commencent par wsk_.

CopierAuthorization: Bearer wsk_…

X-API-Key: wsk_… est accepté comme en-tête alternatif. Une clé est en lecture-écriture ou en lecture seule ; une clé en lecture seule reçoit 403 read_only_key à toute écriture.

En-têtes de requête

Modèle de données du véhicule

Champs acceptés en POST, PUT et PATCH. Les réponses renvoient les mêmes noms, plus les champs en lecture seule uuid, status (published / unlisted), public_url, currency, images, for_sale_since et created_at.

Endpoints

Compte

Référence (sans clé)

Véhicules

Photos

Schémas complets des requêtes et réponses, avec toutes les énumérations : Swagger UI · ReDoc · openapi.json.

Réponse de liste

{
  "count": 37, "limit": 50, "offset": 0, "next_offset": null,
  "results": [ { "uuid": "…", "external_id": "STOCK-4821", "status": "published", … } ]
}

Upsert et mises à jour obsolètes

POST /v1/vehicles avec un external_id que votre garage utilise déjà met à jour ce véhicule (HTTP 200) au lieu d'en créer un second (HTTP 201). Une intégration naïve « tout envoyer chaque nuit » devient ainsi idempotente.

Si vous envoyez aussi external_updated_at, une mise à jour dont l'horodatage est plus ancien que celui enregistré est refusée avec 409 stale_update : un événement en retard ne peut jamais écraser un plus récent. Dans une synchronisation, ce véhicule est signalé skipped_stale et le reste continue.

PATCH ne change que les champs envoyés. PUT est un remplacement complet : les champs optionnels omis sont vidés. Les deux acceptent le même corps que la création.

Synchronisation de l'inventaire

POST /v1/vehicles/sync fait l'upsert d'un inventaire entier en un appel (≤200 véhicules ; répétez pour davantage). Chaque véhicule a besoin d'un external_id.

Copier{
  "complete": true,
  "vehicles": [
    {
      "external_id": "STOCK-4821",
      "make": "Volkswagen",
      "model": "Golf",
      "year": 2022,
      "asking_price": 24950,
      "fuel_type": "petrol",
      "mileage": 41200
    },
    {
      "external_id": "STOCK-4835",
      "make": "Audi",
      "model": "A4",
      "year": 2021,
      "asking_price": 28900,
      "fuel_type": "diesel",
      "body_type": "estate"
    }
  ]
}

• Validation tout ou rien. L'ensemble est validé d'abord. Un véhicule invalide rejette l'appel avec 422 et une carte vehicles par véhicule ; rien n'est écrit.
• complete: true déclare que l'envoi est votre stock entier. Les véhicules gérés par l'API (portant un de vos ids externes) qui en sont absents sont retirés de la vente, jamais supprimés — ils restent dans votre tableau de bord et reviennent si vous les renvoyez.
• Protection contre le vide. Une synchronisation complète sans véhicule nécessite allow_empty: true, sinon 409 empty_snapshot.
• dry_run: true renvoie would_create, would_update, would_unlist et n'écrit rien.
• Emplacements. Les véhicules au-delà de vos emplacements de vente sont enregistrés non publiés avec un avertissement sale_limit_reached au lieu de faire échouer la synchronisation.

Les véhicules ajoutés à la main sur le site ne sont jamais touchés par une synchronisation.

Emplacements de vente

Chaque compte garage dispose d'un nombre de véhicules pouvant être en vente en même temps (niveau gratuit, abonnements, ou un nombre attribué par Driv.one). GET /v1/me renvoie slots.used, slots.limit et slots.available.

Une création ou mise à jour qui dépasserait ce nombre échoue avec 403 sale_limit_reached. Pour libérer un emplacement, faites PATCH {"is_for_sale": false} sur un véhicule — il reste enregistré et peut être remis en vente. Des emplacements supplémentaires s'achètent sur {link}.

Photos

Les photos sont ordonnées ; l'ordre 0 est la photo principale affichée sur les fiches. Les grandes images sont réduites à 2560 px sur le grand côté et réencodées ; tout ce qui dépasse 15 Mo ensuite est refusé.

Avec le véhicule

Envoyez image_urls à la création ou à la mise à jour. Les photos sont téléchargées depuis vos serveurs dans l'ordre donné et remplacent tout le jeu de photos. Omettez le champ pour ne pas toucher aux photos. Si aucune URL n'est accessible, les photos existantes sont conservées et un avertissement est renvoyé.

Une par une

Copiercurl -X POST https://api.driv.one/v1/vehicles/STOCK-4821/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.example-dealer.be/stock/4821/rear.jpg", "order": 1}'

Copiercurl -X POST https://api.driv.one/v1/vehicles/STOCK-4821/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@rear.jpg" -F "order=1"

Réordonner

Copiercurl -X PUT https://api.driv.one/v1/vehicles/STOCK-4821/images/order \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids": [912, 910, 911]}'

Équipements (106 valeurs)

Envoyez les équipements sous forme de slugs dans features et les aides au stationnement dans parking_assist. Seules les valeurs ci-dessous sont acceptées ; les slugs inconnus renvoient 422 en les nommant. Omettre le champ en PATCH conserve les équipements ; envoyer [] les efface. Libellés dans chaque langue : GET /v1/options.

Extérieur features 78

Intérieur features 28

Énumérations

Libellés dans la langue choisie ; toutes les langues sont dans GET /v1/options. Les valeurs inconnues sont refusées, jamais devinées.

vehicle_type

year

1990 – 2027

color est un texte libre ; ces valeurs sont celles que le site traduit.

Erreurs

Les erreurs sont en JSON avec un code error stable et un message lisible ; certaines portent des clés supplémentaires.

{
  "error": "validation_error",
  "message": "One or more fields are invalid.",
  "fields": {
    "fuel_type": [
      "\"gasoline\" is not a valid choice."
    ],
    "features": [
      "Unknown features: sunroof. GET /v1/options lists the accepted values."
    ]
  }
}

Réponses réussies : 200 lecture ou mise à jour, 201 créé, 204 supprimé.

Limites d'utilisation

Chaque clé peut faire 3 000 requêtes par heure. Au-delà, l'API répond 429 avec un en-tête Retry-After. Une synchronisation nocturne complète de quelques centaines de voitures utilise une poignée d'appels ; s'il vous en faut plus, contactez Driv.one.

Les téléchargements de photos comptent dans le même budget via les appels qui les déclenchent, pas par image.