Imagens de carros para sinistros e cotações de seguro

Um formulário de cotação, um registro de apólice e um aviso de sinistro identificam o veículo da mesma forma: pelo VIN, digitado pelo cliente ou lido em um documento de registro. Tudo o que uma pessoa vê depois sobre o carro é texto: um ano, uma marca, um modelo e talvez uma versão. Perguntar "este é o seu veículo?" ao lado de uma linha de texto convida a um sim para qualquer coisa.

Uma imagem do modelo para o qual o VIN decodifica permite que o cliente e o perito confirmem num relance que o registro indica o tipo certo de carro. Ela não consegue mostrar qual carro: um render é uma ilustração de estúdio de uma marca, modelo e ano do catálogo e não retrata nenhum veículo físico específico. Esse único fato define toda a integração abaixo.

• Decodifique na entrada. O fluxo de cotação ou o sistema de apólices decodifica o VIN uma vez, gratuitamente, e armazena o id de veículo do catálogo junto com a apólice. Os sinistros abertos na apólice o herdam.
• Uma só vista em todo lugar. front-3-4, o ângulo principal, em um mesmo quadro na tela de cotação, na bancada de sinistros, no PDF da cotação e no portal da apólice, para que todas as telas mostrem o modelo da mesma forma.
• URLs assinadas, nunca a chave. Navegadores e geradores de PDF carregam URLs sem chave que o seu servidor gera.
• Palavras para o que uma imagem não consegue dizer. Versão, opcionais, a cor registrada, danos e quilometragem continuam em texto e fotos, e a imagem informa que é meramente ilustrativa.

GET /api/v1/vin/{vin} não custa nada e exige uma chave com images:read. Ele retorna os campos decodificados dos dados do vPIC da NHTSA (ano, marca, modelo, versão, série, tipo de carroceria, motor e todos os outros atributos que o vPIC conhece) e, quando o catálogo tem o veículo, um objeto vehicle com seu id estável e um image_path pronto.

Leia o trim: "Carrera, Carrera T, Carrera 4". O padrão deste VIN abrange três versões, então nem a decodificação consegue dizer qual delas a apólice segura, e muito menos uma renderização do 911 2024. Peça ao cliente que confirme a versão, guarde-a junto com series e body_class como texto e deixe a imagem mostrar o modelo.

• Um VIN com dígito verificador incorreto ainda é decodificado, com valid: false e o problema em errors; suggested_vin marca com ! o caractere que o vPIC considera errado, e é isso que você deve mostrar a quem está digitando.
• Um formulário que tenha apenas os primeiros caracteres pode enviar um VIN parcial: pelo menos cinco caracteres, com * para cada posição desconhecida e um year opcional.
• Um 404 significa que o vPIC não tem registro desse padrão. O vPIC cobre veículos fabricados para o mercado dos EUA; para outros mercados, comece pela marca e pelo modelo com POST /api/v1/images/resolve, que também é gratuito.

Armazene data.vehicle.id na apólice como uma string simples e copie-o para cada sinistro aberto contra ela. O id é determinístico e permanente: o mesmo veículo tem o mesmo id em cada deploy e após cada nova versão do catálogo, por isso é seguro usá-lo como chave estrangeira, e cada requisição posterior informa vehicle=veh_78qtwrgh37bkr em vez de escrever a marca e o modelo.

Quando data.vehicle é null, a marca e o modelo decodificados não estão no catálogo, como acontece com reboques e alguns chassis comerciais. Os campos decodificados continuam disponíveis para você exibir. Exiba-os sem imagem e nunca coloque um carro parecido no lugar.

A tela de cotação, a bancada de sinistros e o portal de apólices são aplicativos de navegador, então seu servidor gera URLs assinadas com POST /api/v1/image-urls: 1 crédito por URL no momento em que ela é gerada, até 50 por chamada, e o carregamento é gratuito até ela expirar. Enquadre a imagem uma vez e reutilize o formato: front-3-4 em uma caixa de 640×400 com fit: "contain", e trim com um pouco de padding para que um cupê e uma picape preencham a caixa da mesma forma. Quanto tempo cada URL deve durar depende de onde ela é exibida:

• A bancada de sinistros. Gere a URL quando a tela for renderizada. A validade padrão de 1 hora cobre uma sessão de trabalho, e um sinistro reaberto amanhã recebe uma nova URL.
• O PDF da cotação. Quando o PDF é gerado a partir de HTML, o renderizador carrega a imagem uma vez e a incorpora, então o tempo de validade padrão é mais do que suficiente, e o serviço de PDF nunca tem acesso à sua chave. format: "jpg" aplica a imagem sobre um fundo branco, que é o que um documento pede.
• O portal da apólice e o e-mail de renovação. Eles duram mais do que qualquer tempo de validade, então emita com renew: true e ttl_seconds: 604800 (7 dias). A URL continua funcionando, cada semana adicional em que ela é aberta custa 1 crédito, e renew_days: 365, o máximo permitido, cobre a vigência de uma apólice de um ano.

Configure no painel uma lista de origens permitidas para a chave que gera as URLs: uma URL carregada de outro site responde 403 com origin_not_allowed, enquanto clientes de e-mail e visualizadores de PDF, que não enviam Referer, continuam carregando-a. Revogar a chave invalida todas as URLs que ela gerou.

Coloque o aviso onde está a imagem, não apenas em uma nota de rodapé: no texto alternativo e em uma legenda abaixo da imagem. A renderização mostra a marca, o modelo e o ano em uma pintura que você escolhe, e color pode seguir a cor informada na apólice (um nome de cor predefinida ou qualquer hex). Ainda assim, é o modelo nessa pintura, não o carro do cliente.

• Gratuito: a decodificação de VIN, o resolve, as consultas ao catálogo e todo carregamento de uma URL assinada dentro da sua validade.
• 1 crédito: cada imagem entregue ao seu servidor ou cada URL gerada, e cada semana adicional em que uma URL renovável é aberta.
• Veículos distintos: um funil de cotação recebe muitos veículos diferentes, 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 solicitação acima do limite é recusada antes de qualquer cobrança; portanto, dimensione o plano pelos veículos que você cota, não pelos créditos.

Em um plano pago, a licença cobre uma renderização dentro do que o seu produto gera para os usuários dele, incluindo uma cotação ou um relatório, enquanto o plano estiver ativo; os detalhes estão na licença.

• SDK: client.decodeVin(vin, { year? }) e client.createImageUrls(…), como acima; client.resolve(query) para um veículo sem VIN.
• MCP: decode_vin e create_car_image_urls fazem parte do conjunto principal de ferramentas, então um assistente com o sinistro no contexto pode responder "mostre o modelo segurado" a partir do VIN registrado. A configuração está na página do MCP.