# Manual da API — VIN V3
## Autenticação
Todas as rotas em `public/v3/api/external/*` exigem API key válida.
Header recomendado:
`X-API-Key: SUA_API_KEY`
Também existe suporte a `api_key` por query string para testes controlados.
## Resposta padrão
Sucesso:
- `ok: true`
- `data: {...}`
- `meta: {...}`
- `trace_id`
Erro:
- `ok: false`
- `error.code`
- `error.message`
- `error.details`
- `trace_id`
## Endpoints principais
### VIN completo
`GET /public/v3/api/external/vin_full.php?vin=VIN`
Também aceita JSON body com `vin`.
Retorna a mesma informação funcional da pesquisa VIN do UX:
- VIN validado;
- identificação;
- factory sheet;
- sales codes;
- engine decoder;
- transmission decoder;
- documentos;
- secções técnicas.
### VIN básico legado
`GET /public/v3/api/external/decode.php?vin=VIN`
Retorna estrutura básica do VIN.
### Powertrain legado
`GET /public/v3/api/external/powertrain.php?vin=VIN`
Endpoint antigo. Pode conter resolução técnica separada, mas o decoder real está em `vin_full.php`.
### Vision genérico
`POST /public/v3/api/external/vision.php`
Multipart:
- `image`: ficheiro obrigatório;
- `mode`: `vin_sticker`, `plate_color` ou `dashboard`.
### Scan foto com VIN decode
`POST /public/v3/api/external/scan_photo.php`
Multipart:
- `image`: ficheiro obrigatório;
- `mode`: `vin_sticker`, `plate_color` ou `dashboard`.
Se detectar VIN, também devolve `vin_decoded`.
### Matrícula + cor
`POST /public/v3/api/external/plate_color.php`
Multipart:
- `image`: ficheiro obrigatório.
### Dashboard
`POST /public/v3/api/external/dashboard.php`
Multipart:
- `image`: ficheiro obrigatório.
## Exemplos curl
VIN completo:
`curl -H "X-API-Key: SUA_API_KEY" "https://HOST/public/v3/api/external/vin_full.php?vin=VIN"`
Imagem VIN sticker:
`curl -H "X-API-Key: SUA_API_KEY" -F "mode=vin_sticker" -F "image=@foto.jpg" "https://HOST/public/v3/api/external/scan_photo.php"`
Matrícula + cor:
`curl -H "X-API-Key: SUA_API_KEY" -F "image=@foto.jpg" "https://HOST/public/v3/api/external/plate_color.php"`
Dashboard:
`curl -H "X-API-Key: SUA_API_KEY" -F "image=@foto.jpg" "https://HOST/public/v3/api/external/dashboard.php"`
## Regras do decoder
O decoder real não usa inferência.
Para motor/transmissão:
- requer código explícito de factory sheet ou sales code;
- usa tabela decoder;
- se não houver código explícito, devolve vazio/null.
## Códigos HTTP
- 200: sucesso;
- 401: API key ausente/inválida;
- 422: input inválido;
- 500: erro interno.