API de importación

Mantén tu inventario de Driv.one sincronizado con tu DMS o sistema de stock. Crea y actualiza vehículos, envía inventarios completos, gestiona fotos, a través de una API REST versionada y limitada a tu taller.

La API está pensada para vendedores profesionales, grupos de concesionarios, proveedores de DMS y socios de integración. Los registros que crees aparecen en driv.one bajo tu taller, igual que los autos añadidos a mano.

Primeros pasos

1. Crea una clave de API

Inicia sesión en {link}, elige el taller, ponle un nombre a la clave y cópiala. La clave se muestra una sola vez; si la pierdes, revócala y crea otra.

2. Prueba la autenticación

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

3. Crea un vehículo

Copiarcurl -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 respuesta es el vehículo guardado con su uuid, public_url, currency y fotos, más un arreglo warnings cuando ocurrió algo no fatal (una foto que no se pudo descargar, un modelo que se creó).

URL base y versiones

Copiarhttps://api.driv.one/v1

La versión mayor forma parte de la ruta. Los cambios incompatibles reciben una nueva versión mayor; /v1 conserva su comportamiento. Los cambios aditivos (campos opcionales nuevos, valores nuevos en enumeraciones) pueden aparecer dentro de v1: lee GET /v1/options en lugar de fijar listas en el código.

Las rutas se muestran sin barra final; también se acepta con ella.

Autenticación

Autenticación con token Bearer y una clave de API del taller. Las claves empiezan por wsk_.

CopiarAuthorization: Bearer wsk_…

Se acepta X-API-Key: wsk_… como cabecera alternativa. Una clave es de lectura y escritura o de solo lectura; una clave de solo lectura recibe 403 read_only_key en cualquier escritura.

Cabeceras de la petición

Modelo de datos del vehículo

Campos aceptados en POST, PUT y PATCH. Las respuestas devuelven los mismos nombres, más los campos de solo lectura uuid, status (published / unlisted), public_url, currency, images, for_sale_since y created_at.

Endpoints

Cuenta

Referencia (sin clave)

Vehículos

Fotos

Esquemas completos de petición y respuesta, con todas las enumeraciones: Swagger UI · ReDoc · openapi.json.

Respuesta de listado

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

Upsert y actualizaciones obsoletas

POST /v1/vehicles con un external_id que tu taller ya usa actualiza ese vehículo (HTTP 200) en lugar de crear otro (HTTP 201). Así una integración simple de "enviar todo cada noche" es idempotente.

Si además envías external_updated_at, una actualización con una marca de tiempo más antigua que la guardada se rechaza con 409 stale_update, de modo que un evento retrasado nunca sobrescribe uno más nuevo. Dentro de una sincronización ese vehículo se reporta como skipped_stale y el resto continúa.

PATCH cambia solo los campos que envías. PUT es un reemplazo completo: los campos opcionales que omitas se vacían. Ambos aceptan el mismo cuerpo que la creación.

Sincronización del inventario

POST /v1/vehicles/sync hace upsert de todo un inventario en una llamada (≤200 vehículos; repítela para más). Cada vehículo necesita un external_id.

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

• Validación todo o nada. Primero se valida todo el contenido. Un vehículo inválido rechaza la llamada con 422 y un mapa vehicles por vehículo; no se escribe nada.
• complete: true declara que el contenido es todo tu stock. Los vehículos gestionados por la API (los que llevan uno de tus ids externos) que falten se retiran de la venta, nunca se borran: siguen en tu panel y vuelven si los envías de nuevo.
• Protección contra vacío. Una sincronización completa sin vehículos necesita allow_empty: true; si no, 409 empty_snapshot.
• dry_run: true devuelve would_create, would_update, would_unlist y no escribe nada.
• Cupos. Los vehículos que superen tus cupos de venta se guardan sin publicar con un aviso sale_limit_reached en lugar de hacer fallar la sincronización.

Los vehículos añadidos a mano en el sitio web nunca se tocan en una sincronización.

Cupos de venta

Cada cuenta de taller tiene un número de vehículos que pueden estar en venta al mismo tiempo (nivel gratuito, niveles de suscripción o una cantidad asignada por Driv.one). GET /v1/me devuelve slots.used, slots.limit y slots.available.

Una creación o actualización que supere el cupo falla con 403 sale_limit_reached. Para liberar un cupo, haz PATCH {"is_for_sale": false} a un vehículo: se conserva y puede volver a publicarse. Puedes comprar más cupos en {link}.

Fotos

Las fotos están ordenadas; el orden 0 es la foto principal que aparece en las tarjetas. Las imágenes grandes se redimensionan a 2560 px en el lado largo y se recodifican; lo que supere 15 MB después de eso se rechaza.

Con el vehículo

Envía image_urls al crear o actualizar. Las fotos se descargan de tus servidores en el orden indicado y reemplazan todo el conjunto de fotos. Omite el campo para dejar las fotos como están. Si no se puede descargar ninguna URL, se conservan las fotos existentes y se devuelve un aviso.

De una en una

Copiarcurl -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}'

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

Reordenar

Copiarcurl -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]}'

Equipamiento (106 valores)

Envía el equipamiento como slugs en features y las ayudas de aparcamiento en parking_assist. Solo se aceptan los valores siguientes; los slugs desconocidos devuelven 422 indicándolos. Omitir el campo en PATCH conserva el equipamiento; enviar [] lo vacía. Etiquetas en todos los idiomas: GET /v1/options.

Exterior features 78

Interior features 28

Enumeraciones

Etiquetas en el idioma seleccionado; todos los idiomas están en GET /v1/options. Los valores desconocidos se rechazan, no se adivinan.

vehicle_type

year

1990 – 2027

color es texto libre; estos valores son los que el sitio traduce.

Errores

Los errores son JSON con un código error estable y un message legible; algunos incluyen claves adicionales.

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

Respuestas correctas: 200 lectura o actualización, 201 creado, 204 eliminado.

Límites de uso

Cada clave puede hacer 3 000 peticiones por hora. Por encima, la API responde 429 con una cabecera Retry-After. Una sincronización nocturna completa de unos cientos de autos usa pocas llamadas; si necesitas más, contacta con Driv.one.

Las descargas de fotos cuentan en el mismo presupuesto a través de las llamadas que las provocan, no por imagen.