API de Inventario para Concesionarios

Introducción

La API de inventario te permite publicar y mantener tu catálogo de vehículos en Zokko desde tu propio software de gestión (DMS, ERP o un script). Cada vehículo se identifica por una referencia única —el id de stock de tu sistema— de modo que las llamadas son idempotentes: si la referencia ya existe, se actualiza; si es nueva, se crea. Nunca duplica.

Los anuncios publicados por la API quedan automáticamente marcados como profissionais (con el sello de concesionario), atribuidos a tu ficha y a tu cuenta. No tienes que indicar el tipo de vendedor: se deriva de tu cuenta.

• Base URL: https://zokko.es
• Formato: JSON (request y response) · Content-Type: application/json
• Versión: v1 (prefijo /api/v1/dealer)
• Dos modos de integración: push (tú llamas a la API) o pull (Zokko trae tu feed XML).

Autenticación

Todas las llamadas de inventario se autentican con una clave de API por concesionario en la cabecera Authorization:

Authorization: Bearer zkd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cómo conseguir tu clave

1. Entra en tu panel profesional con tu cuenta de concesionario.
2. Abre la sección «API e integraciones» y pulsa «Generar clave».
3. Copia la clave zkd_live_… que aparece. Solo se muestra una vez; guárdala en un sitio seguro.

Errores de autenticación

Quickstart

Sube tus dos primeros coches en menos de un minuto. Sustituye zkd_live_… por tu clave real:

curl -X POST https://zokko.es/api/v1/dealer/vehicles \
  -H "Authorization: Bearer zkd_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicles": [
      {
        "reference": "REF-A1",
        "make": "Cupra",
        "model": "Leon",
        "version": "VZ",
        "price": 28900,
        "year": 2022,
        "mileage_km": 15000,
        "fuel": "gasolina",
        "transmission": "automatico",
        "city": "Bilbao",
        "region": "País Vasco",
        "images": ["https://tu-dms.com/fotos/refa1-1.jpg"]
      }
    ]
  }'

{
  "success": true,
  "summary": { "total": 1, "created": 1, "updated": 0, "errors": 0 },
  "results": [
    { "reference": "REF-A1", "status": "created", "id": 747, "photos": 1, "photos_failed": 0 }
  ]
}

Campos del vehículo

Cada vehículo del array vehicles acepta los siguientes campos. Solo cuatro son obligatorios; el resto se sanea y normaliza. Un ítem inválido se devuelve con status: "error" sin tumbar el resto del lote.

Subir / actualizar inventario (lote)

Crea o actualiza vehículos por reference. Acepta { "vehicles": [...] } o directamente un array [...] (máximo 200 por llamada). No retira nada: solo toca lo que envías.

curl -X POST https://zokko.es/api/v1/dealer/vehicles \
  -H "Authorization: Bearer zkd_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    { "reference": "REF-A1", "make": "Cupra", "model": "Leon", "price": 28900 },
    { "reference": "REF-B2", "make": "Seat",  "model": "Ibiza", "price": 14500 }
  ]'

{
  "success": true,
  "summary": { "total": 2, "created": 2, "updated": 0, "errors": 0 },
  "results": [
    { "reference": "REF-A1", "status": "created", "id": 747, "photos": 0, "photos_failed": 0 },
    { "reference": "REF-B2", "status": "created", "id": 748, "photos": 0, "photos_failed": 0 }
  ]
}

HTTP: 200 (todo OK) · 207 (mixto: algunos OK, algunos error) · 422 (todos error) · 400 (body inválido). Cada ítem con error devuelve { "reference", "status": "error", "error" }.

Sincronizar inventario completo (espejo del DMS)

El array que envías es tu inventario completo. Zokko crea/actualiza los que mandas y retira automáticamente (archiva) los que ya no aparezcan. Es la forma recomendada para que Zokko sea un espejo fiel de tu DMS.

{
  "success": true,
  "summary": { "total": 120, "created": 4, "updated": 116, "retired": 3, "errors": 0 },
  "retired_references": ["REF-OLD-1", "REF-OLD-2", "REF-OLD-3"],
  "results": [ /* un objeto por vehículo enviado */ ]
}

Listar tu inventario

Devuelve el inventario que tienes en Zokko. Parámetros: status = published | archived | all (por defecto published), limit y offset para paginar.

curl https://zokko.es/api/v1/dealer/vehicles?status=published&limit=50 \
  -H "Authorization: Bearer zkd_live_xxxxxxxxxxxxxxxx"

{
  "success": true,
  "total": 118, "count": 50, "limit": 50, "offset": 0,
  "vehicles": [
    {
      "reference": "REF-A1", "id": 747, "status": "published",
      "title": "Cupra Leon VZ", "make": "Cupra", "model": "Leon",
      "version": "VZ", "year": 2022, "price": 28900, "mileage_km": 15000,
      "fuel": "gasolina", "transmission": "automatico",
      "city": "Bilbao", "region": "País Vasco",
      "image_cover_url": "/api/uploads/motor/dealer-1718-ab12.webp",
      "images": ["/api/uploads/motor/dealer-1718-ab12.webp"],
      "url": "https://zokko.es/motor/coche/cupra-leon-vz-747"
    }
  ]
}

Ver un vehículo por referencia

Devuelve un único vehículo en el formato de salida, o 404 si esa referencia no existe en tu inventario.

curl https://zokko.es/api/v1/dealer/vehicles/REF-A1 \
  -H "Authorization: Bearer zkd_live_xxxxxxxxxxxxxxxx"

Retirar un vehículo

Retira (archiva) el vehículo: deja de mostrarse a los compradores pero la operación es reversible (vuelve a publicarse si lo subes otra vez con status: "available").

{ "success": true, "reference": "REF-A1", "status": "archived", "id": 747 }

Cuenta y plan

Comprueba qué concesionario resuelve tu clave, tu plan y cuántos coches tienes publicados / archivados. Útil para validar la integración.

{
  "success": true,
  "dealer": { "id": 12, "name": "Autos Bilbao", "slug": "autos-bilbao", "verified": true, "city": "Bilbao", "region": "País Vasco", "profile_url": "https://zokko.es/motor/coches/autos-bilbao" },
  "plan": { "account_type": "dealer", "plan": "pro", "plan_key": "pro", "status": "active", "max_listings": 200, "period_end": null },
  "vehicles": { "published": 118, "archived": 7, "total": 125 }
}

Feed XML automático (modo pull)

Si tu DMS ya publica tu inventario como un XML en una URL (formato coches.net, StandVirtual o el genérico de tu sistema), no necesitas escribir código: dile a Zokko dónde está tu feed y nosotros lo traemos y sincronizamos como un espejo (crea, actualiza y retira lo ausente), automáticamente a diario.

Configurarlo desde el panel

1. En tu panel profesional → API e integraciones, pega la URL de tu feed en «URL de tu feed XML» y guarda.
2. Pulsa «Sincronizar ahora» para la primera importación. Verás la última sincronización y el resultado (creados / actualizados / retirados / errores).

O por API, con tu clave

curl -X PUT https://zokko.es/api/v1/dealer/feed \
  -H "Authorization: Bearer zkd_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-dms.com/zokko-feed.xml", "format": "xml" }'

{
  "success": true, "source": "feed_xml",
  "feed_url": "https://tu-dms.com/zokko-feed.xml", "parsed": 120,
  "summary": { "total": 120, "created": 4, "updated": 116, "retired": 2, "errors": 0 },
  "retired_references": ["REF-OLD-1", "REF-OLD-2"]
}

Formato del feed XML

El parser es flexible: reconoce las etiquetas habituales de los feeds del sector (coches.net / StandVirtual / genéricos). Lo esencial es un elemento por vehículo con su referencia, marca, modelo y precio. Ejemplo mínimo válido:

<?xml version="1.0" encoding="UTF-8"?>
<vehicles>
  <vehicle>
    <reference>REF-A1</reference>
    <make>Cupra</make>
    <model>Leon</model>
    <version>VZ</version>
    <price>28900</price>
    <year>2022</year>
    <mileage_km>15000</mileage_km>
    <fuel>gasolina</fuel>
    <transmission>automatico</transmission>
    <city>Bilbao</city>
    <region>País Vasco</region>
    <status>available</status>
    <images>
      <image>https://tu-dms.com/fotos/refa1-1.jpg</image>
      <image>https://tu-dms.com/fotos/refa1-2.jpg</image>
    </images>
  </vehicle>
</vehicles>

Ingesta de fotos

Las URLs de images[] (o las del feed XML) se descargan y re-suben a la infraestructura de Zokko con el mismo procesado que las subidas manuales: rotación según EXIF, redimensionado a ≤ 1600 px y conversión a WebP de calidad optimizada. No guardamos la URL externa: la portada y la galería quedan servidas desde Zokko (p. ej. /api/uploads/motor/dealer-….webp).

• Máximo 20 fotos por vehículo.
• Cada imagen: timeout de descarga 15 s, máx. 15 MB, debe ser un content-type de imagen.
• Si una foto falla, se descarta y se sigue: lo verás en photos_failed del resultado.

Códigos de estado

Todas las respuestas de error tienen la forma { "success": false, "error": "mensaje legible" }.

Límites y rate-limit

Al superar el rate-limit recibirás un 429. Cada respuesta incluye cabeceras estándar RateLimit-* para que tu cliente pueda regularse.

Apoio

¿Dudas con tu integración, tu DMS no exporta XML, o necesitas ayuda con el mapeo de campos? Estamos para ayudarte.

• Painel profissional — genera tu clave y configura tu feed.
• Contactar a Zokko — escríbenos y un agente Pro te acompaña.