Import-API

Houd uw Driv.one-voorraad gelijk met uw DMS of voorraadsysteem. Maak en wijzig voertuigen, stuur complete voorraden, beheer foto's — via een geversioneerde REST-API die beperkt is tot uw werkplaats.

De API is bedoeld voor professionele verkopers, dealergroepen, DMS-leveranciers en integratiepartners. Records die u aanmaakt verschijnen op driv.one onder uw werkplaats, net als handmatig toegevoegde wagens.

Snel starten

1. Maak een API-sleutel

Meld u aan op {link}, kies de werkplaats, geef de sleutel een naam en kopieer hem. De sleutel wordt één keer getoond; bent u hem kwijt, trek hem dan in en maak een nieuwe.

2. Test de authenticatie

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

3. Maak een voertuig

Kopiërencurl -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"
  ]
}'

Het antwoord is het opgeslagen voertuig met zijn uuid, public_url, currency en foto's, plus een warnings-lijst wanneer er iets niet-fataals gebeurde (een foto die niet kon worden opgehaald, een model dat is aangemaakt).

Basis-URL & versies

Kopiërenhttps://api.driv.one/v1

Het hoofdversienummer staat in het pad. Niet-compatibele wijzigingen krijgen een nieuwe hoofdversie; /v1 behoudt zijn gedrag. Aanvullingen (nieuwe optionele velden, nieuwe enumeratiewaarden) kunnen binnen v1 verschijnen — lees GET /v1/options in plaats van lijsten vast te coderen.

Paden worden zonder slash op het einde getoond; mét wordt ook aanvaard.

Authenticatie

Bearer-token-authenticatie met een API-sleutel van de werkplaats. Sleutels beginnen met wsk_.

KopiërenAuthorization: Bearer wsk_…

X-API-Key: wsk_… wordt als alternatieve header aanvaard. Een sleutel is lezen-en-schrijven of alleen-lezen; een alleen-lezen-sleutel krijgt 403 read_only_key bij elke schrijfactie.

Request-headers

Datamodel voertuig

Velden die aanvaard worden bij POST, PUT en PATCH. Antwoorden geven dezelfde namen terug, plus de alleen-lezen velden uuid, status (published / unlisted), public_url, currency, images, for_sale_since en created_at.

Endpoints

Account

Referentie (geen sleutel nodig)

Voertuigen

Foto's

Volledige request- en responseschema's, met alle enumeraties: Swagger UI · ReDoc · openapi.json.

Lijstantwoord

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

Upsert & verouderde updates

POST /v1/vehicles met een external_id die uw werkplaats al gebruikt werkt dat voertuig bij (HTTP 200) in plaats van een tweede aan te maken (HTTP 201). Zo is een eenvoudige integratie "elke nacht alles sturen" idempotent.

Stuurt u ook external_updated_at mee, dan wordt een update met een oudere tijdstempel dan de opgeslagen geweigerd met 409 stale_update, zodat een vertraagd bericht nooit een nieuwer overschrijft. In een sync wordt zo'n voertuig als skipped_stale gemeld en gaat de rest door.

PATCH wijzigt alleen de velden die u stuurt. PUT is een volledige vervanging: optionele velden die u weglaat worden gewist. Beide aanvaarden dezelfde body als aanmaken.

Voorraadsynchronisatie

POST /v1/vehicles/sync doet een upsert van een hele voorraad in één oproep (≤200 voertuigen; herhaal voor meer). Elk voertuig heeft een external_id nodig.

Kopiëren{
  "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"
    }
  ]
}

• Alles-of-niets-validatie. De hele payload wordt eerst gevalideerd. Eén ongeldig voertuig laat de oproep mislukken met 422 en een vehicles-map per voertuig; er wordt niets geschreven.
• complete: true verklaart de payload tot uw volledige voorraad. Door de API beheerde voertuigen (met een van uw externe ids) die ontbreken worden uit de verkoop gehaald, nooit verwijderd — ze blijven in uw dashboard en komen terug als u ze opnieuw stuurt.
• Bescherming tegen leeg. Een complete sync zonder voertuigen heeft allow_empty: true nodig, anders 409 empty_snapshot.
• dry_run: true geeft would_create, would_update, would_unlist terug en schrijft niets.
• Slots. Voertuigen boven uw te-koop-slots worden niet gepubliceerd opgeslagen met een waarschuwing sale_limit_reached, in plaats van de sync te laten mislukken.

Voertuigen die met de hand op de website zijn toegevoegd, worden door een sync nooit aangeraakt.

Te-koop-slots

Elk werkplaatsaccount heeft een aantal voertuigen dat tegelijk te koop mag staan (gratis niveau, abonnementen, of een aantal toegekend door Driv.one). GET /v1/me geeft slots.used, slots.limit en slots.available.

Eén aanmaak of update die het aantal overschrijdt mislukt met 403 sale_limit_reached. Om een slot vrij te maken: PATCH {"is_for_sale": false} op een voertuig — het blijft bewaard en kan later opnieuw te koop gezet worden. Extra slots koopt u op {link}.

Foto's

Foto's zijn geordend; volgorde 0 is de hoofdfoto op de kaarten. Grote afbeeldingen worden verkleind tot 2560 px op de lange zijde en opnieuw gecodeerd; alles boven 15 MB daarna wordt geweigerd.

Met het voertuig

Stuur image_urls bij aanmaken of bijwerken. De foto's worden in de opgegeven volgorde van uw servers gehaald en vervangen de hele fotoset. Laat het veld weg om de foto's ongemoeid te laten. Kan geen enkele URL worden opgehaald, dan blijven de bestaande foto's staan en krijgt u een waarschuwing.

Eén per keer

Kopiërencurl -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}'

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

Herordenen

Kopiërencurl -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]}'

Uitrusting (106 waarden)

Stuur uitrusting als slugs in features en parkeerhulp in parking_assist. Alleen onderstaande waarden worden aanvaard; onbekende slugs geven 422 met hun naam. Het veld weglaten bij PATCH behoudt de uitrusting; [] sturen wist ze. Labels in elke taal: GET /v1/options.

Exterieur features 78

Interieur features 28

Enumeraties

Labels in de gekozen taal; alle talen staan in GET /v1/options. Onbekende waarden worden geweigerd, niet geraden.

vehicle_type

year

1990 – 2027

color is vrije tekst; deze waarden zijn de waarden die de site vertaalt.

Fouten

Fouten zijn JSON met een stabiele error-code en een leesbaar message; sommige bevatten extra sleutels.

{
  "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."
    ]
  }
}

Geslaagde antwoorden: 200 lezen of bijwerken, 201 aangemaakt, 204 verwijderd.

Gebruikslimieten

Elke sleutel mag 3 000 verzoeken per uur doen. Daarboven antwoordt de API 429 met een Retry-After-header. Een volledige nachtelijke sync van enkele honderden wagens gebruikt een handvol oproepen; hebt u meer nodig, neem dan contact op met Driv.one.

Fotodownloads tellen mee in hetzelfde budget via de oproepen die ze veroorzaken, niet per afbeelding.