API de importação

Mantenha o seu inventário Driv.one alinhado com o seu DMS ou sistema de stock. Crie e atualize veículos, envie inventários completos, gira fotos — através de uma API REST versionada e limitada à sua oficina.

A API destina-se a vendedores profissionais, grupos de concessionários, fornecedores de DMS e parceiros de integração. Os registos que criar aparecem em driv.one sob a sua oficina, tal como os carros adicionados à mão.

Início rápido

1. Crie uma chave de API

Inicie sessão em {link}, escolha a oficina, dê um nome à chave e copie-a. A chave é mostrada uma única vez; se a perder, revogue-a e crie outra.

2. Teste a autenticação

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

3. Crie um veí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"
  ]
}'

A resposta é o veículo guardado com o seu uuid, public_url, currency e fotos, mais uma lista warnings quando algo não fatal aconteceu (uma foto que não pôde ser obtida, um modelo que foi criado).

URL base e versões

Copiarhttps://api.driv.one/v1

A versão principal faz parte do caminho. Alterações incompatíveis recebem uma nova versão principal; /v1 mantém o seu comportamento. Acréscimos (novos campos opcionais, novos valores de enumeração) podem surgir dentro da v1 — leia GET /v1/options em vez de fixar listas no código.

Os caminhos são mostrados sem barra final; com barra também é aceite.

Autenticação

Autenticação por token Bearer com uma chave de API da oficina. As chaves começam por wsk_.

CopiarAuthorization: Bearer wsk_…

X-API-Key: wsk_… é aceite como cabeçalho alternativo. Uma chave é de leitura e escrita ou só de leitura; uma chave só de leitura recebe 403 read_only_key em qualquer escrita.

Cabeçalhos do pedido

Modelo de dados do veículo

Campos aceites em POST, PUT e PATCH. As respostas devolvem os mesmos nomes, mais os campos só de leitura uuid, status (published / unlisted), public_url, currency, images, for_sale_since e created_at.

Endpoints

Conta

Referência (sem chave)

Veículos

Fotos

Esquemas completos de pedido e resposta, com todas as enumerações: Swagger UI · ReDoc · openapi.json.

Resposta de listagem

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

Upsert e atualizações obsoletas

POST /v1/vehicles com um external_id que a sua oficina já usa atualiza esse veículo (HTTP 200) em vez de criar outro (HTTP 201). Assim, uma integração simples de "enviar tudo todas as noites" é idempotente.

Se também enviar external_updated_at, uma atualização com uma data mais antiga do que a guardada é recusada com 409 stale_update, para que um evento atrasado nunca substitua um mais recente. Numa sincronização, esse veículo é reportado como skipped_stale e o resto prossegue.

PATCH altera apenas os campos que enviar. PUT é uma substituição completa: os campos opcionais omitidos são limpos. Ambos aceitam o mesmo corpo da criação.

Sincronização do inventário

POST /v1/vehicles/sync faz upsert de um inventário inteiro numa só chamada (≤200 veículos; repita para mais). Cada veículo precisa de um 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"
    }
  ]
}

• Validação tudo ou nada. Todo o conteúdo é validado primeiro. Um veículo inválido rejeita a chamada com 422 e um mapa vehicles por veículo; nada é escrito.
• complete: true declara que o conteúdo é todo o seu stock. Os veículos geridos pela API (com um dos seus ids externos) que faltem são retirados da venda, nunca apagados — ficam no seu painel e voltam se os enviar de novo.
• Proteção contra vazio. Uma sincronização completa sem veículos precisa de allow_empty: true; caso contrário, 409 empty_snapshot.
• dry_run: true devolve would_create, would_update, would_unlist e não escreve nada.
• Vagas. Os veículos além das suas vagas de venda são guardados não publicados com um aviso sale_limit_reached, em vez de fazer falhar a sincronização.

Os veículos adicionados à mão no site nunca são tocados por uma sincronização.

Vagas de venda

Cada conta de oficina tem um número de veículos que podem estar à venda ao mesmo tempo (nível gratuito, subscrições, ou um número atribuído por Driv.one). GET /v1/me devolve slots.used, slots.limit e slots.available.

Uma criação ou atualização que exceda esse número falha com 403 sale_limit_reached. Para libertar uma vaga, faça PATCH {"is_for_sale": false} num veículo — fica guardado e pode voltar a ser publicado. Pode comprar mais vagas em {link}.

Fotos

As fotos são ordenadas; a ordem 0 é a foto principal mostrada nos cartões. As imagens grandes são redimensionadas para 2560 px no lado maior e recodificadas; o que exceder 15 MB depois disso é recusado.

Com o veículo

Envie image_urls ao criar ou atualizar. As fotos são descarregadas dos seus servidores pela ordem indicada e substituem todo o conjunto de fotos. Omita o campo para deixar as fotos como estão. Se nenhum URL puder ser obtido, as fotos existentes mantêm-se e é devolvido um aviso.

Uma de cada vez

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

Equipamento (106 valores)

Envie o equipamento como slugs em features e as ajudas de estacionamento em parking_assist. Só os valores abaixo são aceites; slugs desconhecidos devolvem 422 a nomeá-los. Omitir o campo em PATCH mantém o equipamento; enviar [] limpa-o. Etiquetas em todos os idiomas: GET /v1/options.

Exterior features 78

Interior features 28

Enumerações

Etiquetas no idioma selecionado; todos os idiomas estão em GET /v1/options. Valores desconhecidos são recusados, não adivinhados.

vehicle_type

year

1990 – 2027

color é texto livre; estes valores são os que o site traduz.

Erros

Os erros são JSON com um código error estável e um message legível; alguns trazem chaves extra.

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

Respostas bem-sucedidas: 200 leitura ou atualização, 201 criado, 204 apagado.

Limites de utilização

Cada chave pode fazer 3 000 pedidos por hora. Acima disso, a API responde 429 com um cabeçalho Retry-After. Uma sincronização noturna completa de algumas centenas de carros usa poucas chamadas; se precisar de mais, contacte a Driv.one.

As transferências de fotos contam no mesmo orçamento através das chamadas que as originam, não por imagem.