Documentação Técnica
de Integração

Sumário

1. Introdução

1.1. Sobre o Pedágio Eletrônico

O Pedágio Eletrônico é uma plataforma centralizada que atua como intermediário entre concessionárias de rodovias e motoristas, facilitando o pagamento de transações de passagens em pedágios do tipo NAVI (sem tag ou AVI recusado).

Através do portal unificado (www.pedagioeletronico.com.br), motoristas podem visualizar e pagar suas pendências de múltiplas concessionárias em um único lugar, com suporte a diversos meios de pagamento (PIX, cartão de crédito, carteira digital).

1.2. Objetivo da Integração

Esta documentação descreve o protocolo técnico para que concessionárias de rodovias possam integrar seus sistemas ao Pedágio Eletrônico, permitindo:

• Envio automático de transações NAVI para o portal
• Recebimento de notificações de pagamento em tempo real
• Sincronização bidirecional de status de transações
• Prevenção de dupla cobrança através de sistema de lock
• Auditoria completa de todas as operações

1.3. Benefícios para Concessionárias

2. Visão Geral da Arquitetura

2.1. Componentes do Sistema

A arquitetura do Pedágio Eletrônico é composta pelos seguintes componentes principais:

2.2. Modelo Híbrido de Comunicação

A integração utiliza um modelo híbrido que combina comunicação assíncrona e síncrona para otimizar performance e garantir consistência:

3. Tipos de Dados e Enumerações

Esta seção detalha todos os tipos enumerados (enums) e estruturas de dados utilizados no protocolo de integração. Estes tipos são comuns a ambos os protocolos de comunicação: mensageria assíncrona (RabbitMQ) e REST API síncrona (HTTP).

3.1. Status de Pedido

3.2. Status de Passagem/Transação

3.3. Meio de Pagamento

3.4. Sentido de Via

3.5. Categorias de Veículo

3.6. Formato de Timestamps

# Passagem em 12/11/2025 às 14:30 BRT (horário de Brasília)
from datetime import datetime, timezone, timedelta

# Horário local BRT (UTC-3)
hora_brt = datetime(2025, 11, 12, 14, 30, 0)

# Converter para UTC (adicionar 3 horas)
hora_utc = hora_brt + timedelta(hours=3)  # 17:30 UTC

# Gerar timestamp Unix
timestamp = int(hora_utc.timestamp())  # 1731427200

3.7. Formato de Valores Monetários

4. Comunicação Assíncrona (Mensageria)

As mensagens assíncronas são trocadas via RabbitMQ utilizando o protocolo AMQP. Este modelo é inspirado no protocolo ARTESP 001/14, adaptado para o contexto do Pedágio Eletrônico.

4.1. Mensagem PASSAGEM

Direção: Concessionária → Pedágio Eletrônico
Descrição: Notifica uma transação de passagem sem tag (NAVI) detectada pela concessionária
Prazo de envio: Até 24 horas após a passagem
Fila: passagens.{concessionariaId}

Estrutura da Mensagem

{
  "concessionariaId": 123,
  "osaId": 0,
  "sequencial": 1000,
  "passagemId": "253052020300000451",
  "placa": "ABC1D23",
  "datahora": 1731427200,
  "praca": 101,
  "nomePraca": "P01 - ARUJÁ",
  "pista": 3,
  "sentido": "N",
  "catDetectada": 2,
  "catCobrada": 2,
  "valor": 1250,
  "reenvio": 0
}

Descrição dos Campos

4.2. Mensagem PASSAGEM_PROCESSADA

Direção: Pedágio Eletrônico → Concessionária
Descrição: Resposta sobre o status de processamento de uma passagem
Prazo de envio: Até 36 horas após receber a PASSAGEM
Fila: processadas.{concessionariaId}

Estrutura da Mensagem

{
  "concessionariaId": 123,
  "osaId": 0,
  "sequencial": 2000,
  "passagemId": "253052020300000451",
  "resultado": 1,
  "motivoNaoComp": 0,
  "pagamento": 1731513600,
  "valorPago": 1250,
  "meioPagamento": 0
}

Descrição dos Campos

4.3. Códigos de Resultado

4.4. Motivos de Não Compensação

Quando resultado = 3 (Não compensado), o campo motivoNaoComp indica a razão:

5. Comunicação Síncrona (REST API)

A concessionária deve disponibilizar os seguintes endpoints REST para que o Pedágio Eletrônico possa realizar operações em tempo real durante o processo de pagamento do motorista.

5.1. Criar Pedido e Lockar Transações

Authorization: Basic {token_base64}
X-Concessionaria-Id: 123
Content-Type: application/json
X-Idempotency-Key: 03d82e99-e97f-484b-99e2-65e35d9116d6

{
  "concessionariaId": 123,
  "passagens": [
    "253052020300000451",
    "253052020300000452",
    "253052020300000453"
  ],
  "placaVeiculo": "ABC1D23",
  "chaveIdempotencia": "03d82e99-e97f-484b-99e2-65e35d9116d6"
}

{
  "pedidoId": "PED-2025-06-00001",
  "status": "PENDENTE",
  "valorTotal": 3750,
  "passagens": [
    {
      "passagemId": "253052020300000451",
      "valor": 1250,
      "praca": "P01 - ARUJÁ",
      "data": "2025-11-12T10:30:00Z",
      "status": "LOCKED"
    },
    {
      "passagemId": "253052020300000452",
      "valor": 1250,
      "praca": "P02 - GUARULHOS",
      "data": "2025-11-12T11:15:00Z",
      "status": "LOCKED"
    },
    {
      "passagemId": "253052020300000453",
      "valor": 1250,
      "praca": "P01 - ARUJÁ",
      "data": "2025-11-12T14:20:00Z",
      "status": "LOCKED"
    }
  ],
  "expiracaoLock": "2025-11-12T15:45:00Z",
  "linkPagamento": "https://portal.pedagioeletronico.com.br/pagar/PED-2025-06-00001",
  "chaveIdempotencia": "03d82e99-e97f-484b-99e2-65e35d9116d6"
}

5.2. Consultar Status de Pedido

{
  "pedidoId": "PED-2025-06-00001",
  "status": "PAGO",
  "valorTotal": 3750,
  "dataCriacao": "2025-11-12T15:30:00Z",
  "dataPagamento": "2025-11-12T15:42:00Z",
  "chaveIdempotencia": "03d82e99-e97f-484b-99e2-65e35d9116d6",
  "passagens": [
    {
      "passagemId": "253052020300000451",
      "valor": 1250,
      "status": "PAGO"
    },
    {
      "passagemId": "253052020300000452",
      "valor": 1250,
      "status": "PAGO"
    },
    {
      "passagemId": "253052020300000453",
      "valor": 1250,
      "status": "PAGO"
    }
  ]
}

5.3. Autorizar Liquidação de Transação

{
  "concessionariaId": 123,
  "passagemId": "253052020300000451",
  "pedidoId": "PED-2025-06-00001",
  "valor": 1250,
  "meioPagamento": 0,
  "timestampPagamento": 1731513600
}

{
  "autorizado": true,
  "transacaoId": "TXN-2025-00001234",
  "mensagem": "Transação autorizada para liquidação",
  "timestamp": 1731513600
}

{
  "autorizado": false,
  "motivo": "TRANSACAO_JA_LIQUIDADA",
  "mensagem": "Esta transação já foi paga em outro canal",
  "timestamp": 1731513600
}

6. Fluxo de Integração Completo

6.1. Diagrama de Sequência

6.2. Passo a Passo Detalhado

A concessionária detecta uma passagem sem tag ou AVI recusado em uma de suas praças de pedágio. O sistema de detecção captura: placa, data/hora, valor, categoria, praça e pista.

A concessionária envia uma mensagem PASSAGEM via RabbitMQ para a fila passagens.{concessionariaId}. Este envio deve ocorrer até 24h após a passagem.

{
  "passagemId": "253052020300000451",
  "placa": "ABC1D23",
  "datahora": 1731427200,
  "valor": 1250,
  ...
}

O Pedágio Eletrônico recebe a mensagem, valida os dados e armazena a transação. Em seguida, envia uma resposta PASSAGEM_PROCESSADA com resultado=4 (Provisionado), indicando que a transação foi aceita e está aguardando pagamento.

O motorista acessa o portal do Pedágio Eletrônico, consulta suas pendências por placa e visualiza a transação disponível para pagamento.

O Pedágio Eletrônico chama POST /api/v1/pedidos/criar na API da concessionária, informando quais passagens o motorista deseja pagar. A concessionária "locka" essas transações por 15 minutos, retornando um pedidoId.

O motorista preenche os dados de pagamento no portal (PIX, cartão de crédito, etc).

Para cada passagem do pedido, o Pedágio Eletrônico chama POST /api/v1/transacoes/autorizar. A concessionária valida:

• Passagem existe e não foi paga
• Passagem está lockada no pedido correto
• Lock ainda não expirou

Se tudo estiver correto, retorna autorizado: true.

O Pedágio Eletrônico processa o pagamento com o gateway de pagamento. Após confirmação, marca internamente as transações como pagas.

O Pedágio Eletrônico envia mensagens PASSAGEM_PROCESSADA com resultado=1 (Compensado) via RabbitMQ para a fila processadas.{concessionariaId}.

{
  "passagemId": "253052020300000451",
  "resultado": 1,
  "pagamento": 1731513600,
  "valorPago": 1250,
  "meioPagamento": 0
}

A concessionária recebe a notificação e marca a transação como PAGA em seu sistema interno, fechando o ciclo.

7. Especificações Técnicas

7.1. Autenticação e Segurança

OAuth 2.0 Client Credentials

A autenticação utiliza o fluxo OAuth 2.0 Client Credentials. A concessionária receberá credenciais (client_id e client_secret) do Pedágio Eletrônico.

Obtendo um Token

curl -X POST https://api.pedagioeletronico.com.br/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=sua_client_id" \
  -d "client_secret=seu_client_secret"

Resposta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Usando o Token

Inclua o token no header Authorization de todas as requisições:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Concessionaria-Id: 123
Content-Type: application/json

Comunicação Segura

• TLS 1.2+: Todas as comunicações REST devem usar HTTPS com TLS 1.2 ou superior
• Certificados: Validar certificados SSL em ambiente de produção
• Secrets: Armazenar credenciais em cofres seguros (AWS Secrets Manager, Azure Key Vault, etc)
• IP Whitelist: Opcional - restringir acesso por faixa de IPs

7.2. Configuração de Mensageria

RabbitMQ - Detalhes de Conexão

Filas Dedicadas

Cada concessionária possui filas dedicadas:

• passagens.{concessionariaId} - Para enviar PASSAGEM
• processadas.{concessionariaId} - Para receber PASSAGEM_PROCESSADA

Configurações Recomendadas

{
  "prefetch_count": 10,
  "heartbeat": 60,
  "connection_timeout": 30000,
  "auto_ack": false,
  "durable": true,
  "persistent": true
}

7.3. Sincronização de Tempo

É crítico que os servidores da concessionária estejam sincronizados via NTP para garantir consistência nos timestamps.

Servidores NTP Recomendados (Brasil)

• ntp.usp.br - Universidade de São Paulo
• a.ntp.br - NTP.br (primário)
• b.ntp.br - NTP.br (secundário)
• c.ntp.br - NTP.br (terciário)

Configurar NTP no Linux

# Instalar chrony
sudo apt-get install chrony

# Editar /etc/chrony/chrony.conf
server ntp.usp.br iburst
server a.ntp.br iburst
server b.ntp.br iburst

# Reiniciar serviço
sudo systemctl restart chrony

# Verificar sincronização
chronyc tracking

7.4. Rate Limiting

Para garantir estabilidade, os seguintes limites são aplicados:

Ao exceder o limite, a resposta será:

HTTP/1.1 429 Too Many Requests
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Limite de requisições excedido",
  "retry_after": 60
}

8. Ambientes e Credenciais

Ambiente Sandbox (Testes)

Ambiente Produção

Obtenção de Credenciais

Para obter credenciais de integração:

1. Entre em contato com o time de integração: integracao@pedagioeletronico.com.br
2. Forneça as seguintes informações:
   • Razão social da concessionária
   • CNPJ
   • Nome e email do responsável técnico
   • IPs dos servidores que farão integração (para whitelist)
   • Lista de praças de pedágio e respectivos IDs
3. Você receberá:
   • concessionariaId - Identificador único
   • client_id e client_secret - Para OAuth
   • Credenciais RabbitMQ (usuário e senha)
   • Documentação adicional específica

Processo de Homologação

Após aprovação nos testes de Sandbox, será agendado o Go-Live para ambiente de produção com acompanhamento do time técnico.

9. Tratamento de Erros

9.1. Política de Retry (Reenvio)

Para Mensageria (RabbitMQ)

Implemente retry exponencial com backoff para mensagens que falharam:

import time

def enviar_com_retry(mensagem, max_tentativas=3):
    """
    Envia mensagem com retry exponencial
    """
    for tentativa in range(max_tentativas):
        try:
            enviar_passagem(mensagem)
            return True
        except Exception as e:
            if tentativa < max_tentativas - 1:
                # Backoff exponencial: 2^tentativa segundos
                tempo_espera = 2 ** tentativa
                print(f"⚠️  Tentativa {tentativa + 1} falhou. Aguardando {tempo_espera}s...")
                time.sleep(tempo_espera)
            else:
                print(f"❌ Falha após {max_tentativas} tentativas")
                # Logar erro para análise manual
                raise e

Para REST API

Recomendações de retry por código de status:

9.2. Circuit Breaker

Implemente o padrão Circuit Breaker para proteger sua aplicação de falhas em cascata quando a API do Pedágio Eletrônico estiver indisponível:

• FECHADO (Closed): Sistema operando normalmente
• ABERTO (Open): Sistema detectou muitas falhas, requisições são rejeitadas imediatamente
• MEIO-ABERTO (Half-Open): Após timeout, tenta uma requisição de teste

9.3. Logging e Monitoramento

Logs Obrigatórios

Registre em logs estruturados (JSON) as seguintes informações:

Métricas para Monitorar

• Taxa de sucesso/erro no envio de mensagens
• Latência das chamadas REST
• Número de transações autorizadas vs. recusadas
• Tempo médio entre PASSAGEM e PASSAGEM_PROCESSADA
• Taxa de expiração de locks (pedidos não concluídos)

10. Perguntas Frequentes (FAQ)

❓ O que acontece se eu enviar a mesma passagem duas vezes?

Se você enviar a mesma passagemId duas vezes (com reenvio=0 nas duas), a segunda mensagem será rejeitada com resultado=3 e motivoNaoComp=400 (Passagem inválida/duplicada). Se for um reenvio legítimo (ex: timeout), incremente o campo reenvio para 1, 2, etc.

❓ Como funciona o lock de 15 minutos?

Quando o Pedágio Eletrônico chama POST /pedidos/criar, as transações especificadas ficam "reservadas" por 15 minutos. Durante esse período:

• A concessionária não deve liquidar essas transações por outros canais
• Outras plataformas parceiras não conseguem criar pedidos com essas transações
• Após 15 minutos sem pagamento, o lock expira automaticamente

❓ E se o motorista pagar em outro canal durante o lock?

Isso não deveria acontecer se o sistema da concessionária respeitar o lock. Mas se acontecer, ao chamar POST /transacoes/autorizar, a concessionária deve retornar autorizado: false com motivo: "TRANSACAO_JA_LIQUIDADA". O Pedágio Eletrônico cancelará o pedido e não cobrará o motorista.

❓ Posso enviar passagens com mais de 24h?

Tecnicamente sim, mas a mensagem pode ser rejeitada com motivoNaoComp=6 (Passagem enviada fora do prazo). O ideal é enviar assim que possível após a passagem, de preferência em tempo real ou em lotes a cada hora.

❓ Como sei se uma transação foi efetivamente paga?

Você receberá uma mensagem PASSAGEM_PROCESSADA com resultado=1 (Compensado) ou resultado=6 (Liquidado por outro meio). Só marque como PAGO em seu sistema após receber essa confirmação.

❓ Preciso implementar todos os 3 endpoints REST?

Sim. Os endpoints são essenciais para o fluxo de pagamento:

• POST /pedidos/criar - Cria lock e previne dupla cobrança
• GET /pedidos/:id - Permite consultar status do pedido
• POST /transacoes/autorizar - Valida autorização em tempo real

❓ O que são "centavos" nos valores?

Para evitar problemas de precisão com números decimais, todos os valores monetários são representados em centavos (inteiro). Multiplique o valor em reais por 100:

• R$ 12,50 = 1250 centavos
• R$ 0,50 = 50 centavos
• R$ 100,00 = 10000 centavos

❓ Preciso converter horários para UTC?

Sim! Todos os timestamps (datahora, pagamento, timestampPagamento) devem estar em UTC-0 (Unix timestamp). Se sua concessionária opera em horário de Brasília (UTC-3), adicione 3 horas ao horário local antes de converter.

❓ Qual a diferença entre resultado=1 e resultado=6?

• resultado=1 (Compensado): Pago diretamente no portal do Pedágio Eletrônico
• resultado=6 (Liquidado por outro meio): Pago em outro parceiro integrado (ex: banco, app de pagamentos, Arrecada+)

Ambos significam que a transação foi paga e deve ser marcada como PAGA no seu sistema.

❓ Como testar a integração antes do Go-Live?

Use o ambiente Sandbox:

1. Solicite credenciais de sandbox ao time de integração
2. Configure sua aplicação para apontar para as URLs de sandbox
3. Envie pelo menos 50 transações de teste
4. Teste todos os cenários: sucesso, erros, lock, autorização, etc.
5. Valide os logs e métricas
6. Solicite homologação oficial

❓ Onde encontro suporte técnico?

Entre em contato com o time de integração:

• Email: integracao@pedagioeletronico.com.br
• Telefone: +55 (51) 99211-6696 (horário comercial)
• Portal de Suporte: suporte.pedagioeletronico.com.br
• Slack (para parceiros homologados): Entre em contato para convite

11. Glossário

12. Contato e Suporte