# Integração A52 — levantamento inicial

Documentação consultada: https://integracao.a52.com.br/doc/

## Confirmado publicamente

A A52 disponibiliza documentação Swagger para integração. O site institucional também confirma que a plataforma integra dados de rastreadores e macros/eventos do veículo e que o produto logístico trabalha com viagens, veículos, entregas, comprovantes/canhotos e mapa operacional.

## Limitação desta revisão

O Swagger é carregado dinamicamente. No ambiente de análise usado para esta versão, a página pública abriu como Swagger UI, porém a especificação OpenAPI/endpoints não ficou exposta ao crawler. Por isso **não foram inventados** base URL da API, autenticação, nomes de endpoints, campos ou webhooks.

## O que precisamos extrair do contrato A52 antes do conector real

1. Ambiente/base URL da API (produção e homologação, se houver).
2. Método de autenticação e ciclo de renovação do token.
3. Identificador canônico do veículo (placa, ID A52, dispositivo etc.).
4. Identificador de viagem/serviço e possibilidade de guardar a referência da OS MD.
5. Endpoints para localização atual e/ou histórico de posições.
6. Campos de latitude, longitude, data/hora e hodômetro/distância acumulada.
7. Eventos/macros disponíveis para início de viagem, chegada/saída da origem e chegada/saída do destino.
8. Webhooks ou outra entrega push; caso não haja, regras/limites de polling.
9. Paginação, timezone, rate limit e política de retentativas.
10. Códigos HTTP e payloads de erro.

## Estrutura já pronta no Sistema MD

A migration V40 cria `integracao_eventos`, tabela genérica de auditoria para A52, GPS da frota e futuras APIs. Todo payload pode ser armazenado antes de qualquer processamento, associado posteriormente a uma OS e marcado como recebido/processando/sucesso/erro/ignorado.

O serviço `App\\Services\\RegistroIntegracao` centraliza o registro e as tentativas. Os serviços já existentes `AtualizadorMarcosViagem` e `AtualizadorGeolocalizacaoViagem` permanecem como portas de aplicação dos eventos na OS.

## Fluxo alvo

A52/GPS -> integracao_eventos (payload bruto) -> identificação da OS -> validação/normalização -> AtualizadorMarcosViagem / AtualizadorGeolocalizacaoViagem -> OS/histórico -> status sucesso ou erro.