# Vision Dados — Monetizar Acervo de Imagens

**Quem é você.** Você opera captura própria — concessionária de pedágio com câmeras OCR/ALPR nas praças, estacionamento com gates de leitura de placa, ou ponto fiscal com câmeras de fluxo. Captura por exigência regulatória ou operacional, mantém storage caro, sem retorno financeiro direto.

**Problema.** Acervo de imagens cresce mês a mês. Custo de retenção e backup só sobe. Compliance LGPD é inteiramente seu. Nenhuma receita vem do dado.

**Solução Movvia.** A Movvia ingere o acervo via API REST, enriquece com metadados e distribui para clientes B2B autorizados (seguradoras, bancos, frotistas, órgãos de investigação). Você recebe participação por passagem ingerida e aceita. A Movvia atua como operadora; você permanece controladora dos dados.

## Como encaixa no seu produto

- Você já captura as imagens — não há novo hardware nem mudança operacional.
- A integração é uma chamada `POST /passagens-visuais` por passagem (ou em lote via pipeline).
- Modelo de receita por volume mensal de passagens ingeridas — quanto mais você envia, melhor o tier.
- Compliance LGPD gerenciado em conjunto: a API expõe `DELETE /passagens-visuais/{id}` para atender Art. 18 sem complexidade operacional.
- O canal de consumo B2B é separado desta API — clientes finais não acessam seu acervo direto.


## Fluxo em 3 passos

### Passo 1 — Descobrir identidade (uma vez no onboarding)


```bash
curl -u "$USUARIO:$SENHA" \
  https://api.pedagioeletronico.com.br/vision-dados/v1/me
```

Resposta:


```json
{
  "data": {
    "concessionariaId": 42,
    "nomeFantasia": "Concessionária Exemplo S.A.",
    "status": "ATIVA"
  }
}
```

Guarde `concessionariaId` para o header `x-concessionaria-id` em todas as chamadas seguintes.

### Passo 2 — Enviar passagem (por evento ou em lote)

`multipart/form-data` com dois campos: `image` (binário) + `metadata` (JSON):


```bash
curl -X POST https://api.pedagioeletronico.com.br/vision-dados/v1/passagens-visuais \
  -u "$USUARIO:$SENHA" \
  -H "x-concessionaria-id: 42" \
  -F "image=@passagem.jpg;type=image/jpeg" \
  -F 'metadata={"externalId":"prc-sp07-20260424-000123","capturedAt":"2026-04-24T15:22:10Z","latitude":-23.611040,"longitude":-46.702120,"placa":"XYZ9A87","tipoVeiculo":"CAMINHAO","rodovia":"SP-150","km":18.7,"classificacaoEixos":3};type=application/json'
```

Resposta `201 Created`:


```json
{
  "data": {
    "id": "01J7H9Z9C4K8V3N2M5Q6P7R8T9",
    "externalId": "prc-sp07-20260424-000123",
    "status": "RECEBIDA",
    "capturedAt": "2026-04-24T15:22:10Z",
    "receivedAt": "2026-04-24T15:22:11Z"
  }
}
```

Guarde o `id` (ULID) para consultas e exclusões.

### Passo 3 — Atender exclusão LGPD (sob demanda)


```bash
curl -X DELETE -u "$USUARIO:$SENHA" \
  -H "x-concessionaria-id: 42" \
  https://api.pedagioeletronico.com.br/vision-dados/v1/passagens-visuais/01J7H9Z9C4K8V3N2M5Q6P7R8T9
```

Retorna `202 Accepted` com `scheduledDeletionAt` (SLA 72h para apagamento do binário).

## Metadados — campos e enriquecimento

**Obrigatórios:**

| Campo | Tipo | Restrição |
|  --- | --- | --- |
| `externalId` | string | 1–100 chars; chave de idempotência por concessionária |
| `capturedAt` | ISO-8601 UTC | Janela de 7 dias no passado, +5 min de tolerância no futuro |
| `latitude` / `longitude` | number | WGS-84 |
| `placa` | string | 1–20 chars; aceita OCR parcial e placas estrangeiras |


**Opcionais (impactam o valor comercial):**

| Campo | Impacto | Notas |
|  --- | --- | --- |
| `tipoVeiculo` | Alto | `AUTO`, `MOTO`, `CAMINHAO`, `ONIBUS`, `OUTRO` |
| `classificacaoEixos` | Alto | Essencial para clientes de frete |
| `rodovia` + `km` | Alto | Habilita filtros geográficos precisos |
| `velocidadeKmh` | Médio | Análise de risco para seguradoras |
| `sentido`, `faixa`, `pracaId`, `equipamentoId` | Baixo–Médio | Rastreabilidade interna |


Clientes B2B pagam por dados com maior granularidade — campos opcionais aumentam o valor unitário do dado.

## Idempotência — `externalId`

A chave de deduplicação é `(concessionariaId, externalId)`. Reenvio com mesmo `externalId`:

- Retorna `200 OK` (não `201 Created`).
- Devolve o registro original.
- **Não** re-armazena binário nem sobrescreve dados.


Use o identificador único da passagem no seu sistema legado como `externalId`. Reprocesse lotes sem verificação prévia: `201` = criado agora, `200` = já existia. `GET /passagens-visuais/{id}` serve como endpoint de reconciliação.

`DELETE` também é idempotente — chamar em passagem já `EXCLUIDA` retorna `202` com o `scheduledDeletionAt` original.

## Ciclo de vida da passagem


```
POST → RECEBIDA ──► PROCESSADA (indexada, disponível B2B)
            │
            ├──► EXCLUIDA (DELETE LGPD, binário apagado em 72h)
            │
            └──► REJEITADA (validação pós-upload falhou)
```

## LGPD — papéis e exclusão

| Papel | Quem | Responsabilidade |
|  --- | --- | --- |
| Controladora | Você (concessionária) | Define finalidade, responde ao titular |
| Operadora | Movvia | Armazena e distribui conforme contrato |


**Base legal:** Art. 7º II (obrigação legal) + Art. 7º IX (legítimo interesse no contrato de concessão). Distribuição B2B ampara-se no Art. 7º V (execução de contrato).

**Direito à eliminação (Art. 18, V):** ao receber solicitação do titular, chame `DELETE /passagens-visuais/{id}`. A Movvia apaga o binário em até 72h e mantém apenas metadados anonimizados (ULID + hash) para auditoria conforme Art. 16, I. Após exclusão, `GET /passagens-visuais/{id}` retorna `200` com `status: EXCLUIDA` e nenhum campo de PII.

Detalhes operacionais e fluxo completo em [LGPD compartilhado](/compartilhado/lgpd).

## Códigos de resposta

| HTTP | Código | Causa |
|  --- | --- | --- |
| 201 | — | Passagem criada |
| 200 | — | `externalId` já existia (idempotente) |
| 400 | `METADATA_INVALIDO` | JSON malformado ou `capturedAt` fora da janela de 7 dias |
| 400 | `COORDENADAS_INVALIDAS` | `lat`/`long` fora do range WGS-84 |
| 401 | `NAO_AUTENTICADO` | Basic Auth ausente ou inválido |
| 403 | `ACESSO_NEGADO` | `x-concessionaria-id` não bate com a credencial ou conta `SUSPENSA` |
| 413 | `IMAGEM_MUITO_GRANDE` | Acima de 15 MB |
| 415 | `FORMATO_NAO_SUPORTADO` | Não é JPEG/PNG/WEBP |
| 429 | `RATE_LIMIT_EXCEDIDO` | Use o header `Retry-After` |


## Modelo de receita típico

A concessionária recebe participação por passagem ingerida e aceita por clientes B2B, calculada mensalmente com base no volume e no tier contratado. Metadados enriquecidos aumentam o valor unitário — clientes de frete e seguradoras pagam mais por passagens com `tipoVeiculo` + `classificacaoEixos` + `rodovia` + `km` preenchidos.

Reenvios idempotentes (`200`) e consultas (`GET`) **não** geram cobrança. Apenas passagens `RECEBIDA`/`PROCESSADA` entram no volume mensal faturado. Passagens `REJEITADA` não contam.

Volumetria, tiers e pricing — `comercial@movvia.com.br`.

## Próximo passo

1. Solicite credenciais de homologação em `comercial@movvia.com.br`.
2. Faça `GET /me` para obter o `concessionariaId`.
3. Envie a primeira passagem seguindo o Passo 2 acima — em menos de 10 minutos.
4. Consulte a [Referência da API](/apis/estabelecimentos-comerciais/vision-dados/openapi) para o contrato completo (schemas, eventos, todos os códigos de erro).