Skip to main content

Módulo 07: Veículos & FIPE — API

Status: Rascunho Inicial Regras de negócio: ver regras-negocio/07_veiculos_fipe.md Domínio: ver dominio/veiculo.md

1. Contratos de API (RESTful)​

1.1 Veículos do Cliente​

GET /api/clientes/{cliente_id}/veiculos
  Auth: Consultor | Gestor | Admin
  Return: [{ id, tipo, placa, marca, modelo, ano_fabricacao, ano_modelo, chassi, codigo_fipe, valor_base_informado }]

POST /api/clientes/{cliente_id}/veiculos
  Auth: Consultor | Gestor
  Body: {
    tipo,
    placa?,
    chassi?,
    renavam?,
    marca,
    modelo,
    ano_fabricacao,
    ano_modelo,
    cor?,
    codigo_fipe?,
    valor_base_informado?
  }
  Return: { id }
  Errors:
    422 — placa e chassi ausentes simultaneamente
    409 — placa já cadastrada para outro veículo no tenant

GET /api/veiculos/{id}
  Auth: Consultor (cliente na carteira) | Gestor | Admin
  Return: { ...atributos completos, propostas_associadas[], contratos[], vistorias[] }

PUT /api/veiculos/{id}
  Auth: Consultor | Gestor
  Body: { placa?, chassi?, renavam?, cor?, valor_base_informado? }
  Nota: tipo, marca, modelo, ano_fabricacao e ano_modelo são imutáveis após criação.
  Return: 200 OK

1.2 Serviços FIPE​

GET /api/fipe/busca-placa
  Auth: Consultor | Gestor | Admin
  Query: ?placa=ABC1D23
  Return: {
    placa,
    marca,
    modelo,
    ano_fabricacao,
    ano_modelo,
    chassi_mascarado,
    codigo_fipe,
    valor_fipe_atual,
    mes_referencia
  }
  Nota: Internamente o CRM consome a API externa configurada no tenant.
  Errors:
    404 — Placa não encontrada na API externa
    503 — API externa indisponível (sugerir entrada manual)

GET /api/fipe/marcas
  Auth: Público (requer token de sessão)
  Query: ?tipo=carros | motos | caminhoes
  Return: [{ codigo, nome }]
  Nota: Consulta o cache local sincronizado (CSV mensal).

GET /api/fipe/modelos
  Auth: Público (requer token de sessão)
  Query: ?tipo=carros&marca_id=123
  Return: [{ codigo, nome }]

GET /api/fipe/anos
  Auth: Público (requer token de sessão)
  Query: ?tipo=carros&marca_id=123&modelo_id=456
  Return: [{ codigo, nome, valor_atual, mes_referencia }]

1.3 Administração do Cache FIPE (Admin)​

GET /api/admin/fipe/status
  Auth: Admin | Super Admin
  Return: { ultima_sincronizacao_at, mes_referencia, total_registros, status: "OK | DESATUALIZADO | SINCRONIZANDO" }

POST /api/admin/fipe/sincronizar
  Auth: Admin | Super Admin
  Return: { job_id, status: "ENFILEIRADO" }
  Nota: Execução assíncrona. O progresso pode ser consultado via /api/admin/jobs/{job_id}.

2. Schemas de Dados​

Veículo​

{
  "id": "uuid",
  "tenant_id": "uuid",
  "cliente_id": "uuid",
  "tipo": "CARRO | MOTO | CAMINHAO | BICICLETA | OUTROS",
  "marca": "string",
  "modelo": "string",
  "ano_fabricacao": "integer",
  "ano_modelo": "integer",
  "placa": "string | null",
  "chassi": "string | null",
  "renavam": "string | null",
  "cor": "string | null",
  "codigo_fipe": "string | null",
  "valor_base_informado": "decimal | null",
  "created_at": "datetime",
  "updated_at": "datetime"
}

FipeHistorico (tabela interna)​

{
  "id": "uuid",
  "codigo_fipe": "string",
  "tipo": "CARRO | MOTO | CAMINHAO",
  "marca": "string",
  "modelo": "string",
  "ano_referencia": "string",
  "valor": "decimal",
  "mes_referencia": "YYYY-MM",
  "importado_em": "datetime"
}

3. Segurança e Boas Práticas​

RegraImplementação
Silo de dadostenant_id validado em toda operação. Consultor só acessa veículos de clientes da sua carteira.
Imutabilidadetipo, marca, modelo, ano_fabricacao e ano_modelo não são aceitos no body de PUT. Backend deve ignorar ou rejeitar com 400 se enviados.
Congelamento de FIPEO valor monetário FIPE não é armazenado no veículo. É consultado e congelado na Proposta no momento da criação (ver Módulo 08).
Credenciais da API externaA chave da API de dados veiculares é armazenada criptografada (AES-256) nas configurações do tenant. Nunca exposta nas respostas da API.
Sincronização assíncronaO endpoint POST /api/admin/fipe/sincronizar apenas enfileira o job — não executa sincronamente. Usar sistema de filas (ex: Bull, Celery) para processar em background.
Fallback documentadoSe a API externa retornar 503, o sistema registra o erro em log e retorna 503 ao frontend com mensagem orientando o usuário a usar a entrada manual.