Documentación de la API

Publica autos desde tu propio sistema con las mismas exigencias que el formulario de Vende tu auto. Base: /api/v1. Todas las respuestas son JSON.

Autenticación

Crea una API key en Perfil → API keys (requiere el perfil completo) y envíala en cada solicitud:

Authorization: Bearer am_live_xxxxxxxxxxxxxxxx

La clave se muestra una sola vez, vence en 30 días, 90 días o 1 año y puedes revocarla cuando quieras. Máximo 5 claves activas. Trátala como una contraseña y no la expongas en código de navegador.

Flujo para publicar

Pide una URL de subida por cada imagen (POST /api/v1/autos/images).
Sube el archivo a esa URL con PUT.
Consulta GET /api/v1/autos/images/status hasta que la imagen sea accepted (o rejected).
Publica el auto con POST /api/v1/autos.

1. Solicitar URL de subida

POST /api/v1/autos/images

{
  "fileName": "frente.jpg",
  "fileType": "image/jpeg",
  "fileSize": 2345678
}

Tipos: image/jpeg, image/png, image/webp, image/heic, image/heif. La extensión debe coincidir con el tipo y el tamaño máximo es 15 MB.

Respuesta 201:

{
  "uploadUrl": "https://...s3.amazonaws.com/...",
  "objectKey": "raw-images/<tu-id>/<id>-<firma>-frente.jpg",
  "method": "PUT",
  "headers": { "Content-Type": "image/jpeg" },
  "expiresInSeconds": 300
}

2. Subir el archivo

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/jpeg" \
  --data-binary @frente.jpg

El archivo debe tener exactamente el tipo y el tamaño declarados.

3. Estado de la imagen

GET /api/v1/autos/images/status?objectKey=<objectKey>

Cada imagen pasa por nuestro validador automático. Consulta cada ~2 segundos hasta recibir una respuesta final.

202 { "status": "processing" }
200 { "status": "accepted", "url": "https://...amazonaws.com/accepted/....webp" }
200 { "status": "rejected", "message": "..." }

Solo las imágenes accepted subidas por tu cuenta se pueden publicar. Las rechazadas no.

4. Publicar un auto

POST /api/v1/autos con Content-Type: application/json (máx. 32 KB). Cualquier campo no listado se rechaza.

Campo	Tipo	Regla
`marca`	string, obligatorio	Una de las marcas del formulario (ej: Toyota).
`modelo`	string, obligatorio	Modelo que corresponda a la marca (ej: Corolla).
`año`	entero, obligatorio	Entre 1900 y el año actual + 1.
`precio`	entero, obligatorio	Mayor a 0 y hasta 300.000.000.
`region`	string, obligatorio	Región de Chile, como en el formulario (ej: Arica y Parinacota).
`comuna`	string, obligatorio	Comuna que pertenezca a la región.
`kilometraje`	entero, obligatorio	Entre 0 y 1.000.000.
`tipo_combustible`	enum, obligatorio	Bencina, Diesel, Eléctrico, Híbrido o Gas.
`transmision`	enum, obligatorio	Manual o Automática.
`cilindrada`	entero, obligatorio	Entre 0 y 10.000 (cc).
`estado`	enum, obligatorio	Nuevo o Usado.
`comentario`	string \| null, opcional	Descripción, máx. 2000 caracteres.
`mostrar_whatsapp / mostrar_telefono / mostrar_correo`	boolean, por defecto false	Al menos uno debe ser true.
`mostrar_nombre`	boolean, por defecto false	Muestra tu nombre en la publicación (no cuenta como medio de contacto).
`imagen_url`	array, obligatorio	De 1 a 10 objetos { url, is_main? }, sin repetidas. is_main marca la portada: es opcional (si no marcas ninguna, la primera es la portada) y solo una puede ser true. Las URLs salen del paso 3 (estado aprobado).
`publicado`	boolean, por defecto true	Si la publicación queda visible.

Ejemplo:

curl -X POST https://compradeautos.cl/api/v1/autos \
  -H "Authorization: Bearer am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "marca": "Toyota",
    "modelo": "Corolla",
    "año": 2020,
    "precio": 12500000,
    "region": "Arica y Parinacota",
    "comuna": "Arica",
    "kilometraje": 45000,
    "tipo_combustible": "Bencina",
    "transmision": "Automática",
    "cilindrada": 1800,
    "estado": "Usado",
    "comentario": "Único dueño, mantenciones al día.",
    "mostrar_whatsapp": true,
    "imagen_url": [
      { "url": "https://...amazonaws.com/accepted/....webp", "is_main": true }
    ]
  }'

Respuesta 201: { "id": 123, "message": "Auto publicado exitosamente." }

Gestionar tus autos

Solo puedes ver y modificar tus propios autos. Un auto ajeno o eliminado responde 404.

`GET /api/v1/autos?page=1&limit=20`	Lista tus autos (máx. 50 por página): `{ autos, page, limit, total }`.
`GET /api/v1/autos/:id`	Detalle de un auto.
`PUT /api/v1/autos/:id`	Reemplaza el auto. Mismo cuerpo y reglas que publicar; los campos opcionales que omitas vuelven a su valor por defecto, salvo `publicado`, que se conserva.
`PATCH /api/v1/autos/:id`	Modifica solo los campos enviados. El auto resultante se valida completo con las mismas reglas que publicar (por ejemplo, si cambias `region` debes enviar una `comuna` de esa región). Pasar `{"publicado": false}` lo oculta.
`DELETE /api/v1/autos/:id`	Elimina el auto (deja de mostrarse).

Al modificar imágenes, las que ya tiene el auto se conservan tal cual; las nuevas deben subirse y aprobarse con el flujo de arriba (pasos 1 a 3). Entre 1 y 10 imágenes; la portada es la que marques con is_main o, si no marcas ninguna, la primera.

Errores y límites

`401`	Falta la clave, es inválida, venció o fue revocada.
`403`	Origen no permitido (solo con sesión por cookie).
`413 / 415`	Cuerpo demasiado grande / Content-Type distinto de JSON.
`404`	El auto no existe o no es tuyo.
`422`	Datos inválidos. Incluye `details: [{ path, message }]` con cada error.
`429`	Límite excedido. Respeta el encabezado `Retry-After`.

Publicar: 10 por minuto y 30 por día.
Solicitar URLs de subida: 30 por minuto y 300 por día.
Consultar estado de imágenes y ver autos: 120 por minuto.
Modificar y eliminar: 30 por minuto.
Todas las solicitudes: 120 por minuto por IP.