Imágenes de coches para anuncios de subastas

Un catálogo de subasta se publica en cuanto llegan los vehículos en consignación: un VIN, un número de lote y una fecha de venta para cada vehículo. Las fotos llegan cuando el vehículo llega al patio y el fotógrafo llega al vehículo, lo que en parte de una subasta ocurre después de que se abran las pujas. Hasta entonces, cada uno de esos lotes es un recuadro gris junto a una línea de texto.

Un render de catálogo llena el hueco con el año de modelo correcto. Pero una subasta es justo donde un render nunca debe hacerse pasar por el coche: los pujadores valoran el estado, y un render no muestra ninguno, porque no representa ningún vehículo físico concreto. Todo lo que sigue se deriva de tener presentes ambas cosas a la vez.

• Un render por lote a partir de su VIN, que se muestra solo hasta que llegan las fotos propias del lote.
• Un selector del catálogo para los lotes cuyo VIN no se puede decodificar.
• Una etiqueta en la imagen: "Render de catálogo, no este lote".
• Una URL por lote, generada una sola vez con una Idempotency-Key, vigente mientras dure la subasta.

GET /api/v1/vin/{vin} es gratis. Cuando el catálogo tiene el vehículo, la respuesta incluye data.vehicle.id, el id estable que debe guardar en el lote; la versión, la carrocería y el motor decodificados se quedan en el texto del lote. El catálogo abarca de 1990 a 2027, así que el stock más antiguo de una subasta se renderiza igual que el más nuevo. La guía de seguros explica una decodificación campo por campo, y la documentación de VIN trata los VIN parciales y los errores.

Algunos lotes llegan sin un VIN que se pueda decodificar: un vehículo fabricado para otro mercado, un VIN que la fuente escribió mal, una hoja de consignación con un año, una marca y un modelo y nada más. Dote al formulario de consignación de tres menús desplegables alimentados por GET /api/v1/vehicles, que es gratuito y público: ?year= lista las marcas que tienen algún modelo en ese año, y ?year=&makeId= lista los modelos de esa marca, cada uno con el id de vehículo de ese año de modelo.

El mismo catálogo es el paquete abierto @meterapp/vehicle-db, así que los desplegables también pueden funcionar sin conexión con la misma lista. En cualquier caso, el lote termina guardando el mismo tipo de id que un VIN decodificado, y ningún paso posterior tiene que escribir el nombre de un vehículo.

Cuando llega una hoja de consignación completa de una vez, POST /api/v1/vehicles/check lee hasta 2000 entradas por llamada, cada una tal como la escribe la hoja y con el número de lote como su ref, y responde a todas: una coincidencia con el id que debe guardar, sugerencias, un fallo o una fila no válida. No se renderiza nada ni se cobra nada; la documentación de vehículos tiene los detalles.

Ponga la etiqueta en la propia imagen, donde se posa la mirada del pujador, y en el texto alternativo, no solo en la descripción de abajo. El estado, el kilometraje, los daños, el equipamiento y la pintura del coche van en el texto del lote y, cuando existan, en las fotos. Cuando lleguen las fotos, el render se retira.

Genere la URL del lote al darlo de alta con POST /api/v1/image-urls y una Idempotency-Key formada a partir de la venta y el lote, con letras, dígitos, ., _, : y -. La URL se paga al generarse (1 crédito), así que sin clave un alta reintentada la generaría y pagaría dos veces. Con una:

• La misma clave con el mismo cuerpo dentro de un plazo de 24 horas reproduce la primera respuesta, incluida la misma URL, con Idempotent-Replayed: true y sin un segundo cargo.
• La misma clave con un cuerpo distinto devuelve un 422, y un reintento que se adelanta a la primera solicitud devuelve un 409 con un Retry-After. Así que fije todo el cuerpo, incluida la vigencia, al crear el lote, y guárdelo junto con el lote.
• Guarde también la URL en el lote: la clave protege los reintentos, y la URL guardada es lo que leen las páginas durante el resto de la subasta.

Un catálogo completo importado de una vez puede generar hasta 50 lotes por llamada, con una clave por tanda; cada URL de la respuesta repite el vehículo y las opciones para los que se generó.

ttl_seconds admite hasta 604800 (7 días); un valor mayor se limita a ese máximo. Para una subasta que cierra dentro de la semana, establézcalo en el tiempo que falta hasta el cierre. Así, la imagen provisional deja de funcionar cuando terminan las pujas y, a partir de entonces, la URL responde 403.

• Una venta con plazo de más de 7 días: genere la URL con renew: true, ttl_seconds al máximo y renew_days cubriendo la venta. Cada semana adicional en la que se abre el lote cuesta 1 crédito, las semanas sin actividad no cuestan nada y la renovación se detiene en renews_until.
• Mantenga max_uses en 0, el valor predeterminado: una URL ilimitada se puede almacenar en caché públicamente durante toda su vigencia, mientras que una limitada es private, no-store y envía cada carga al origen.
• Restrinja la clave que genera las URL a los dominios de su subasta en el panel: una imagen de lote copiada en otro sitio responde 403.

Cada lote es un vehículo distinto, salvo que dos lotes compartan marca, modelo y año, y cada plan limita los vehículos distintos al mes: Free 100, Pro 2500 y Business 15.000; Enterprise: sin límite. Un vehículo ya servido este mes siempre se permite, y una petición en bloque que superaría el límite se rechaza entera, antes de cobrar nada, con el plan y el límite en la respuesta. Dimensione el plan según los lotes que publique en un mes, no según los créditos. La historia de marketplace explica cómo dosificar una importación grande dentro de los límites de tasa y de renderizado.