API de importação

Mantenha seu inventário Driv.one alinhado com seu DMS ou sistema de estoque. Crie e atualize veículos, envie inventários completos, gerencie fotos — por meio de uma API REST versionada e limitada à sua oficina.

A API é destinada a vendedores profissionais, grupos de concessionárias, fornecedores de DMS e parceiros de integração. Os registros que você criar aparecem em driv.one na sua oficina, assim como os carros adicionados manualmente.

Início rápido

1. Crie uma chave de API

Faça login em driv.one/garage-owner/api-keys, escolha a oficina, dê um nome à chave e copie-a. A chave é mostrada uma única vez; se você 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 salvo com 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 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 são aceitos.

Autenticação

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

CopiarAuthorization: Bearer wsk_…

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

Cabeçalhos da requisição

Modelo de dados do veículo

Campos aceitos em POST, PUT e PATCH. As respostas retornam os mesmos nomes, mais os campos somente leitura uuid, status (published / unlisted), public_url, currency, images, for_sale_since e created_at.

Endpoints

Conta

Referência (sem chave)

Veículos

Vagas

Webhooks

Fotos

Esquemas completos de requisição 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 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 você também enviar external_updated_at, uma atualização com uma data mais antiga do que a salva é recusada com 409 stale_update, para que um evento atrasado nunca substitua um mais recente. Em uma sincronização, esse veículo é reportado como skipped_stale e o resto prossegue.

PATCH altera apenas os campos que você 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 em uma 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 é gravado.
• complete: true declara que o conteúdo é todo o seu estoque. Os veículos gerenciados pela API (com um dos seus ids externos) que faltarem são retirados da venda, nunca excluídos — ficam no seu painel e voltam se você 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 retorna would_create, would_update, would_unlist e não grava nada.
• Vagas. Os veículos além das suas vagas de venda são salvos não publicados com um aviso sale_limit_reached, em vez de fazer a sincronização falhar.

Os veículos adicionados manualmente no site nunca são alterados 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, assinaturas, ou um número atribuído por Driv.one). GET /v1/me retorna slots.used, slots.limit e slots.available.

Quando todas as vagas estão ocupadas, um carro colocado à venda não é recusado: ele espera em uma fila (status queued, aviso queued_for_slot) e fica à venda sozinho, o mais antigo primeiro, assim que uma vaga é liberada - um carro retirado, vendido ou excluído, ou mais vagas compradas em driv.one/garage-owner/slots/purchase. Envie queue_if_full: false para obter o antigo 403 sale_limit_reached.

Colocar muitos veículos à venda

POST /v1/vehicles/publish recebe uma lista dos seus veículos na ordem em que você quer publicá-los. As vagas livres são preenchidas primeiro; o resto fica na fila nessa ordem. A resposta indica quais carros ficaram à venda, quais esperam (com seu lugar na fila) e quantas vagas faltam. GET /v1/slots mostra o mesmo a qualquer momento: os carros à venda, a fila e slots_needed.

Copiarcurl -X POST https://api.driv.one/v1/vehicles/publish \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"vehicles": ["STOCK-4821", "STOCK-4822", "STOCK-4823"]}'

{
  "published": [{"uuid": "…", "external_id": "STOCK-4821"}],
  "queued": [{"uuid": "…", "external_id": "STOCK-4822", "position": 1},
             {"uuid": "…", "external_id": "STOCK-4823", "position": 2}],
  "already_published": [], "not_found": [],
  "slots": {"limit": 10, "used": 10, "available": 0, "queued": 2, "slots_needed": 2},
  "notice": {"code": "slots_needed", "slots_needed": 2, "buy_url": "https://driv.one/garage-owner/slots/purchase", "message": "…"}
}

Enquanto houver carros esperando, o titular da conta é informado de quantas vagas extras são necessárias - na plataforma, por e-mail e com o webhook slots.needed - de novo apenas quando esse número aumenta. POST /v1/vehicles/unpublish retira carros da venda ou da fila; as vagas liberadas passam imediatamente para os próximos carros em espera (promoted_from_queue).

Sincronização bidirecional

A API também informa o que acontece com seus veículos na plataforma: vendas, carros adicionados ou alterados no site ou nos apps, e exclusões. Obtenha as alterações com o feed de alterações, receba-as por webhooks, ou ambos.

Feed de alterações

GET /v1/vehicles?updated_since= retorna todos os seus veículos alterados depois desse momento, da alteração mais antiga para a mais recente, incluindo vendidos e retirados. Salve o server_time da resposta e envie-o como updated_since da próxima vez. As exclusões estão em GET /v1/vehicles/deleted?since=.

Copiarcurl "https://api.driv.one/v1/vehicles?updated_since=2026-09-28T08:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.driv.one/v1/vehicles/deleted?since=2026-09-28T08:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status vendido

Um carro vendido pela plataforma aparece com status: "sold", sold_via: "platform" e sold_at - também quando o vendedor o marcou no site. Informe uma venda do seu lado com {"sold": true}; colocar o carro à venda de novo limpa a venda. status=sold lista esses carros.

Copiarcurl -X PATCH https://api.driv.one/v1/vehicles/STOCK-4821 \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"sold": true, "sold_via": "elsewhere"}'

Webhooks

Registre uma URL https e enviaremos a ela (POST) um evento JSON a cada alteração nos seus veículos. A resposta ao registro traz o secret que assina cada chamada - ele só é mostrado uma vez. As alterações feitas com sua própria chave de API não são reenviadas, a menos que você defina include_own_changes: true. events limita os eventos recebidos.

Copiarcurl -X POST https://api.driv.one/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://dms.example.com/hooks/marketplace"}'

Conteúdo

{
  "id": "4127",
  "event": "vehicle.sold",
  "occurred_at": "2026-09-28T09:14:03.512Z",
  "source": "platform",
  "workshop": {
    "id": 90,
    "name": "Example Motors"
  },
  "data": {
    "vehicle": {
      "uuid": "…",
      "external_id": "STOCK-4821",
      "status": "sold",
      "sold_via": "platform",
      "sold_at": "2026-09-28T09:14:03Z",
      "make": "Volkswagen",
      "model": "Golf",
      "…": "…"
    }
  }
}

Verificar a assinatura

Cada chamada traz X-Webhook-Event, X-Webhook-Id e X-Webhook-Signature: t=<hora unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de t + "." + corpo bruto com o seu secret. Recuse chamadas cujo t tenha mais de 5 minutos.

Copiarimport hashlib, hmac

def verify(secret, header, raw_body):
    parts = dict(p.split("=", 1) for p in header.split(","))
    mac = hmac.new(secret.encode(), (parts["t"] + ".").encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])

Responda com um 2xx em menos de 10 segundos. Caso contrário, há nova tentativa após 1 min, 5 min, 30 min, 2 h, 6 h e 12 h; após 50 falhas seguidas o webhook é desativado (PATCH {"is_active": true} o reativa). As entregas podem chegar repetidas ou fora de ordem: use id para ignorar duplicados e o updated_at do veículo para manter o mais recente. Os eventos vehicle.updated são agrupados durante 20 segundos.

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 baixadas dos seus servidores na ordem indicada e substituem todo o conjunto de fotos. Omita o campo para deixar as fotos como estão. Se nenhuma URL puder ser obtida, as fotos existentes são mantidas e um aviso é retornado.

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 aceitos; slugs desconhecidos retornam 422 indicando quais são. Omitir o campo em PATCH mantém o equipamento; enviar [] esvazia a lista. 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 extras.

{
  "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 excluído.

Limites de uso

Cada chave pode fazer 3 000 requisições 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, entre em contato com Driv.one.

Os downloads de fotos contam no mesmo orçamento por meio das chamadas que os originam, não por imagem.