# Serviço portuário

**Quem é você.** Você opera uma área portuária concessionada — a cobrança é gerada pela entrada ou saída de veículos de carga, passageiros ou de apoio logístico na área sob sua jurisdição.

**Problema.** Cobrança de acesso portuário envolve múltiplos tipos de veículo, CNPJ transportador, horário de pico e regras tarifárias complexas. Processamento manual é lento e gera fila no acesso.

**Solução Movvia.** Você publica a cobrança na entrada ou saída do veículo. A rede de liquidantes permite pagamento automático vinculado ao CNPJ transportador — sem dinheiro em espécie na portaria.

## Como encaixa no seu produto

- Cobrança publicada no momento de entrada ou saída do veículo na área portuária.
- Identificação por placa (veículo) e opcionalmente CNPJ do transportador via `metadata`.
- Regras de horário de pico e categoria tarifária configuradas no onboarding.
- Campo `metadata` suporta `tipo_operacao`, `cnpj_transportador`, `numero_dta`, `terminal` para integração com sistemas de controle portuário.
- Liquidação confirmada via webhook — portão liberado após `pe.passagem.paga` ou no fluxo pós-pago (faturamento mensal ao transportador).


## Fluxo

### Passo 1 — Publicar a cobrança na entrada


```http
POST /ec-api/v1/passagens
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
Content-Type: application/json

{
  "referenciaExterna": "PORTO-2026-00198",
  "placa": "JKL0M12",
  "valor": 85.00,
  "tipo": "ACESSO_PORTUARIO",
  "localCobranca": "Terminal de Paranaguá — Portão 3",
  "capturadoEm": "2026-04-23T06:30:00Z",
  "metadata": {
    "tipo_operacao": "ENTRADA",
    "cnpj_transportador": "12345678000190",
    "numero_dta": "DTA-2026-00998",
    "terminal": "APPA-T3"
  }
}
```

### Passo 2 — Receber confirmação de pagamento


```json
{
  "evento": "pe.passagem.paga",
  "referenciaExterna": "PORTO-2026-00198",
  "valorLiquidado": 85.00,
  "liquidanteId": "liq_frota_ss",
  "liquidadoEm": "2026-04-23T06:30:04Z"
}
```

### Passo 3 — Consultar cobranças por CNPJ transportador


```http
GET /ec-api/v1/passagens?desde=2026-04-01&metadata.cnpj_transportador=12345678000190
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
```

## Modelo de receita típico

Ticket médio portuário é significativamente maior que pedágio convencional. A taxa Movvia é percentual sobre o volume liquidado, com modelo enterprise disponível para grandes terminais. Repasse em D+0 ou D+1 conforme contrato. Para faturamento mensal por CNPJ transportador, consulte o modelo de cobrança consolidada no onboarding.

## Próximo passo

- [Publicar primeira cobrança](/estabelecimentos-comerciais/tutorials/publicar-primeira-cobranca)
- [Referência da API](/apis/estabelecimentos-comerciais/vision-dados/openapi)