Imagens de carros para anúncios de leilão

Um catálogo de leilão é publicado assim que os lotes consignados chegam: um VIN, um número de lote e uma data de venda para cada carro. As fotos vêm quando o carro chega ao pátio e o fotógrafo chega ao carro, o que, para parte de um leilão, acontece depois que os lances já começaram. Até lá, cada um desses lotes é uma caixa cinza ao lado de uma linha de texto.

Um render do catálogo preenche o espaço com o ano-modelo certo. Um leilão também é exatamente onde um render nunca pode se passar pelo carro: os licitantes precificam o estado de conservação, e um render não mostra nada disso, porque não retrata nenhum veículo físico específico. Tudo o que vem a seguir decorre de levar essas duas coisas em conta ao mesmo tempo.

• Um render por lote a partir do VIN, exibido só até chegarem as fotos do próprio lote.
• Um seletor de catálogo para os lotes cujo VIN não é decodificado.
• Um aviso na imagem: "Renderização do catálogo, não este lote".
• Uma URL por lote, gerada uma única vez com uma Idempotency-Key, válida enquanto durar a venda.

GET /api/v1/vin/{vin} é gratuito. Quando o catálogo tem o veículo, a resposta traz data.vehicle.id, o id estável a ser armazenado no lote; a versão, a carroceria e o motor decodificados ficam no texto do lote. O catálogo vai de 1990 a 2027, então o estoque mais antigo de um leilão é renderizado como o mais novo. O guia de seguros explica uma decodificação campo a campo, e a documentação de VIN trata de VINs parciais e erros.

Alguns lotes chegam sem um VIN decodificável: um veículo fabricado para outro mercado, um VIN digitado errado na origem, uma ficha de consignação com ano, marca e modelo e nada mais. Coloque no formulário de consignação três menus suspensos alimentados por GET /api/v1/vehicles, que é gratuito e público: ?year= lista as marcas com algum modelo naquele ano, e ?year=&makeId= lista os modelos dessa marca, cada um com o id de veículo daquele ano-modelo.

O mesmo catálogo é o pacote aberto @meterapp/vehicle-db, então os menus suspensos também podem funcionar offline com a mesma lista. De qualquer forma, o lote fica com o mesmo tipo de ID de um VIN decodificado, e nenhuma etapa seguinte precisa escrever o nome de um carro.

Quando uma planilha de consignação inteira chega de uma vez, POST /api/v1/vehicles/check lê até 2.000 entradas por chamada, cada uma escrita como está na planilha e com o número do lote como ref, e responde a todas: uma correspondência com o id a armazenar, sugestões, uma não correspondência ou uma linha inválida. Nada é renderizado e nada é cobrado; a documentação de vehicles traz os detalhes.

Coloque o aviso na própria imagem, onde o olhar do licitante pousa, e no texto alternativo, não apenas na descrição abaixo. Estado, quilometragem, danos, opcionais e a pintura do carro pertencem ao texto do lote e, quando existirem, às fotos. Quando as fotos chegarem, a renderização sai.

Emita a URL do lote no cadastro com POST /api/v1/image-urls e uma Idempotency-Key formada a partir do leilão e do lote, usando letras, dígitos, ., _, : e -. A URL é paga no momento em que é emitida (1 crédito), então, sem uma chave, um cadastro repetido emitiria e pagaria duas vezes. Com uma chave:

• A mesma chave com o mesmo corpo em até 24 horas reproduz a primeira resposta, incluindo a mesma URL, com Idempotent-Replayed: true e sem uma segunda cobrança.
• A mesma chave com um corpo diferente resulta em 422, e uma nova tentativa que ultrapassa a primeira requisição resulta em 409 com um Retry-After. Portanto, defina tudo no corpo, incluindo o tempo de validade, quando o lote for criado, e armazene-o junto com o lote.
• Armazene também a URL no lote: a chave protege as novas tentativas, e a URL armazenada é o que as páginas leem pelo resto do leilão.

Um catálogo inteiro importado de uma vez pode gerar até 50 lotes por chamada, com uma chave por envio; cada URL na resposta repete o veículo e as opções para os quais foi gerada.

ttl_seconds vai até 604800 (7 dias); um valor maior é limitado a esse máximo. Para um leilão que termina dentro da semana, defina-o como o tempo restante até o encerramento. Assim, a imagem provisória para de funcionar quando os lances terminam e, depois disso, a URL responde 403.

• Uma venda com prazo de mais de 7 dias: gere com renew: true, ttl_seconds no máximo e renew_days cobrindo toda a venda. Cada semana adicional em que o lote é aberto custa 1 crédito, semanas sem acesso não custam nada e a renovação termina em renews_until.
• Mantenha max_uses em 0, o padrão: uma URL ilimitada pode ser armazenada em cache publicamente durante toda a sua validade, enquanto uma limitada é private, no-store e envia cada carregamento para a origem.
• Restrinja a chave que gera as URLs aos domínios do seu leilão no painel: uma imagem de lote copiada para outro site responde 403.

Cada lote é um veículo distinto, a menos que dois lotes compartilhem marca, modelo e ano, e cada plano limita os veículos distintos por mês: Free 100, Pro 2.500 e Business 15.000; Enterprise não tem limite. Um veículo já atendido neste mês é sempre permitido, e uma requisição em massa que ultrapassaria o limite é recusada por inteiro, antes de qualquer cobrança, com o plano e o limite na resposta. Dimensione o plano pelos lotes que você anuncia em um mês, não pelos créditos. A história do marketplace explica como espaçar uma importação grande dentro dos limites de taxa e de renderização.