Como transformar um VIN ou uma planilha de estoque em uma foto para cada veículo no software da concessionária

Um registro de estoque em um CRM, um ERP ou um sistema de gestão de concessionárias (DMS) começa como um VIN, um número de estoque e um preço. A foto chega quando o fotógrafo do pátio chega, e para alguns veículos ela nunca chega: uma unidade em trânsito, um carro recebido na troca ainda em recondicionamento, um importado cujo nome de modelo não corresponde a nada no feed de imagens do DMS, um carro dos anos 1990 do qual ninguém licenciou uma foto de imprensa. Todas as telas que exibem esse registro — a lista do vendedor, a avaliação do comprador, o orçamento do cliente — mostram um espaço reservado cinza.

As ferramentas para concessionárias e importação na API preenchem esse espaço reservado com o que o registro já tem. Se ele tem um VIN, a imagem está a uma decodificação gratuita de distância. Se tem só uma linha numa planilha de estoque, a resolução por texto livre chega lá. De qualquer forma, o registro acaba guardando um id de veículo estável, e todas as telas renderizam o mesmo carro da mesma maneira.

• Decodifique na entrada. O VIN é decodificado uma vez, quando o registro é criado, e o id de veículo do catálogo é armazenado ao lado dele. Nada nas etapas seguintes precisa escrever uma marca ou um modelo.
• Uma vista para a lista, outra para o detalhe. Um side reto em uma caixa larga para listas de estoque; front-3-4 para a página de detalhes e o orçamento.
• Anos antigos. O estoque de importados e usados remonta aos anos 1990 e é renderizado como os recém-chegados: o catálogo vai de 1990 até o ano-modelo atual, incluindo modelos do mercado doméstico japonês.
• URLs assinadas dentro do app. O CRM é um navegador, então carrega URLs assinadas sem chave geradas pelo servidor, até cinquenta por chamada, renovando-as para registros que duram mais de uma semana.

GET /api/v1/vin/{vin} não custa nada e exige apenas uma chave de API. Ele retorna o ano, a marca, o modelo, a versão, a classe de carroceria, o motor e todos os demais atributos decodificados que os dados vPIC da NHTSA conhecem e, quando o catálogo tem o veículo, um objeto vehicle com seu id estável e um image_path pronto. VINs parciais também funcionam: pelo menos cinco caracteres, * para cada posição desconhecida, além de uma dica opcional de year.

O estoque importado costuma chegar como planilha: um ano, uma marca, um nome de modelo na grafia que a casa de leilões usou, um código de grade ou versão. POST /api/v1/images/resolve é gratuito e determinístico: extrai da frase as palavras de ano, cor e vista, busca no catálogo com o que sobra e retorna parâmetros exatos com um nível de confiança no qual você pode se basear.

O veículo está certo (o Toyota Voxy 2019), mas a confiança é low, porque "ZS" é uma versão que o catálogo não conhece e a correspondência teve de contorná-la. Em uma importação em lote, trate high como resolvido e encaminhe medium e low para revisão humana com a lista candidates. Quando a planilha já tem o ano e a marca em colunas próprias, envie-os nos campos year e make e deixe só o modelo em query; a correspondência fica muito mais precisa. Uma frase sem palavras de veículo resulta em 400, e uma marca sem modelo correspondente resulta em 404, que lista os anos da marca para que você possa pedir o modelo.

Seja qual for o caminho que o levou até lá, armazene vehicle.id (ou params.vehicle_id) no registro do estoque como uma coluna de string simples. Ele é determinístico e permanente: o mesmo veículo tem o mesmo id em todo deploy e após cada nova versão do catálogo, então é seguro usá-lo como chave estrangeira. A partir daí, toda solicitação de imagem é vehicle=veh_…, que não tem como ser digitada errado, e uma marca renomeada por um fabricante ou reclassificada por uma fonte nunca quebra uma URL armazenada.

Listas de estoque são largas e baixas, então a vista lateral reta em uma caixa 2:1 é a escolha comum: todas as unidades ficam voltadas para o mesmo lado e apoiadas na mesma linha de base. trim=1&padding=6 recorta no carro antes de ajustar, então uma Hilux e um Yaris preenchem a linha da mesma forma; fit=contain mantém a tela exatamente em 640×320 com margens transparentes. A página de detalhes usa front-3-4 em 1024, e as duas compartilham um cache: uma pintura que você não especificou sai prata em ambas.

O CRM roda em um navegador, e um navegador nunca deve ter a chave de API. Quando uma tela lista uma página de estoque, o servidor gera uma URL assinada por registro com POST /api/v1/image-urls (até cinquenta por chamada; a imagem de cada URL conta como uma imagem de veículo do mês) e a página as carrega como qualquer imagem. Duas configurações importam para um registro que fica em estoque por meses:

• ttl_seconds: 604800 com renew: true: a URL continua funcionando após o TTL de sete dias, e uma renovação conta a imagem uma vez no mês em que ocorre, e nada mais se ela já tiver sido contada naquele mês. Meses em que ninguém olha o carro não contam nada.
• Uma Idempotency-Key por página da sincronização: uma requisição repetida reproduz a primeira resposta e nada é gerado duas vezes.

Restrinja a chave que gera as URLs à origem do CRM no painel, e uma URL que vazar para outro site responderá 403. Revogar a chave invalida todas as URLs que ela gerou. Se as imagens de veículo do mês do plano se esgotarem, uma renovação responde 402 e a mesma URL volta a funcionar quando a cota for renovada ou o plano for ampliado. O ciclo de vida completo está na documentação de URLs assinadas.

• SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) e client.createImageUrls(…), como acima.
• MCP: decode_vin, resolve_vehicle, get_car_image e create_car_image_urls fazem parte do conjunto principal de ferramentas, então um assistente com o sistema de estoque no contexto consegue responder a "foto do estoque 4471" a partir do VIN do registro. A configuração está na página do MCP; os campos e erros do decodificador estão na documentação de VIN.