Interfaces de Eventos
Referência da API
Em Homologação:
Swagger - API de Serviços Pedágio Eletrônico Senatran v3
Em Produção:
API de Serviços Pedágio Eletrônico Senatran v3
Eventos
Passagem
Art. 5º inciso I da PORTARIA SENATRAN Nº 442, DE 10 DE JUNHO DE 2025.
| Atributo | Tipo | Obrigatório? | Permite Atualização?*** | Descrição | Exemplo Avulso | Exemplo TAG |
|---|---|---|---|---|---|---|
| idPassagem | String (36) | Sim | Não | Identificação da Passagem – UUID | "a1b2c3d4-e5f6-7890-1234-567890abcdef" | "a1b2c3d4-e5f6-7890-1234-567890abcdef" |
| modeloCobranca | int | Sim | Não | Modelo - 1 Passagem, 2 Viagem | 1 | 1 |
| dataHoraEntrada | ****Timestamp (ISO-8601) | Sim | Não | Data/Hora da Passagem | "2026-03-27T08:15:30-03:00" | "2026-03-27T08:15:30-03:00" |
| dataHoraSaida | ****Timestamp (ISO-8601) | Não ** | Sim | Data/Hora Saída em caso de cobrança por viagem | "2026-03-27T08:16:45-03:00" | "2026-03-27T08:16:45-03:00" |
| localPorticoEntrada | String (36) | Sim | Não | Pórtico Entrada/Passagem | "a1b2c3d4-e5f6-7890-aaaa-111111111001" | "a1b2c3d4-e5f6-7890-aaaa-111111111001" |
| localPorticoSaida | String (36) | Não ** | Sim | Pórtico Saída em caso de cobrança por viagem | "a1b2c3d4-e5f6-7890-bbbb-111111111002" | "a1b2c3d4-e5f6-7890-bbbb-111111111002" |
| placa | String (7) | Sim | Sim | Placa | "ABC1234" | "ABC1234" |
| idClassificacao | Integer | Sim | Sim | ID_CATEGORIA_OSA | 1 | 1 |
| tag | String (10) | Não | Sim | Nº Série TAG | "TAG0000001" | |
| mdfe | Boolean | Não | Sim | MDFe | false | false |
| operadoraTag | int | Não | Sim | Operadora Tag | 1 | |
| dataHoraAtualizacao | ****Timestamp (ISO-8601) | Sim | Sim | Data Atualização | "2026-03-27T08:16:50-03:00" | "2026-03-27T08:16:50-03:00" |
| status | int | Não | Sim | 1 Ativa, 2 Cancelada | 1 | 1 |
** obrigatório no caso de cobrança por viagem
*** permite atualização enquanto o status de pagamento do evento pagamento for Em Processamento e o status da passagem for Ativa. Como exceção, a concessionária também pode alterar o status da passagem para Cancelada quando o pagamento estiver Pendente de Pagamento ou Vencido.
**** Os atributos do tipo Timestamp (ISO-8601) seguem o padrão AAAA-MM-DDThh:mm:ss seguido do fuso horário:
- data e hora são separadas pela letra
T(ex.:2026-09-24T17:49:00); - o fuso horário é informado ao final do valor, de duas formas possíveis:
Z: indica horário UTC (deslocamento zero em relação ao Tempo Universal Coordenado);- um deslocamento explícito, como
-03:00, indicando que o horário informado está 3 horas atrasado em relação ao UTC (analogamente,+03:00indicaria 3 horas adiantado).
O freeflow armazena os eventos no fuso horário America/Sao_Paulo (UTC-3). Ao receber um valor com fuso horário explícito, a API converte o instante recebido para esse fuso antes de persistir o evento — ou seja, 10:00:00Z e 07:00:00-03:00 representam o mesmo instante e resultam na mesma gravação.
Exemplo: o envio de "dataHoraEntrada": "2026-10-26T10:00:00Z" resulta na gravação de 2026-10-26T07:00:00 no horário de Brasília — o mesmo instante, apenas convertido para o fuso local.
Atenção: se o valor enviado não indicar fuso horário (ex.: "2026-10-26T10:00:00", sem Z nem deslocamento), a API assume que o horário já está no fuso America/Sao_Paulo e não realiza nenhuma conversão — o valor é gravado exatamente como recebido. Para evitar ambiguidade, a concessionária deve sempre informar o deslocamento explicitamente.
Regras de Alterações do Evento Passagem
Campos obrigatórios:
idPassagem
modeloCobranca
dataHoraEntrada
localPorticoEntrada
placa
idClassificacao
dataHoraAtualizacao
dataHoraSaida -> obrigatório no caso de cobrança por viagem
localPorticoSaida -> obrigatório no caso de cobrança por viagem
Campos imutáveis:
idPassagem
modeloCobranca
dataHoraEntrada
localPorticoEntrada
Campos alteráveis:
Quando a passagem estiver com:
Situação: Ativa
Status de Pagamento: Em Processamento
os seguintes campos poderão ser atualizados:
dataHoraSaida
localPorticoSaida
placa
idClassificacao
tag
mdfe
operadoraTag
dataHoraAtualizacao
status
Pagamento
Art. 5º inciso II da PORTARIA SENATRAN Nº 442, DE 10 DE JUNHO DE 2025.
| Atributo | Tipo | Obrigatório? | Permite Atualização? | Descrição | Exemplo Avulso | Exemplo TAG |
|---|---|---|---|---|---|---|
| idPassagem | String (36) | Sim | Não | Identificação Passagem | "f47ac10b-58cc-4372-a567-0e02b2c3d479" | "f47ac10b-58cc-4372-a567-0e02b2c3d479" |
| valorCobrado | Decimal | Sim | Sim*** | Valor Cobrado | 10.00 | 9.20 |
| dataHoraLimitePagamento | Timestamp (ISO-8601) | Sim | Sim*** | Limite Pagamento | "2025-09-30T23:59:59Z" | |
| statusTag | int | Não | Sim | 1 Liberado, 2 Bloqueado | 1 | |
| statusPagamento | int | Sim | Sim | 1 Proc,2 Pago,3 Pend,4 Venc,5 Isento, ... | 3 | 2 |
| dataHoraPagamento | Timestamp (ISO-8601) | Não ** | Sim | Data/Hora Pagamento | "2025-10-26T10:06:00Z" | |
| tipoCobranca | int | Sim | Sim | 1 Automático,2 Avulso | 2 | 1 |
| operadorPagamento | String (36) | Não | Sim | Operador Pagamento | "c3d4e5f6-a7b8-9012-cccc-000000000099" | "c3d4e5f6-a7b8-9012-cccc-000000000099" |
| valorPago | Decimal | Não ** | Sim | Valor Pago | 9.20 | |
| dataHoraAtualizacao | Timestamp (ISO-8601) | Sim | Sim | Atualização | "2025-10-26T10:16:00Z" | "2025-10-26T10:07:00Z" |
** obrigatório quando statusPagamento = PAGO
*** permite atualização enquanto o status de pagamento for Em Processamento.
Regras de Alterações do Evento Pagamento
Campos Obrigatórios:
idPassagem
valorCobrado
dataHoraLimitePagamento
statusPagamento
tipoCobranca
dataHoraAtualizacao
dataHoraPagamento -> obrigatório quando statusPagamento = PAGO
valorPago -> obrigatório quando statusPagamento = PAGO
Campos imutáveis:
idPassagem
Alterações permitidas quando o status for "Em Processamento":
valorCobrado
dataHoraLimitePagamento
statusTag
dataHoraAtualizacao
tipoCobranca
statusPagamento
operadorPagamento
dataHoraPagamento
valorPago
Alterações permitidas na transição para "Pago":
Quando o status do pagamento for alterado de Pendente de Pagamento ou Vencido para Pago dentro do prazo ou Pago fora do prazo, somente os seguintes campos poderão ser atualizados:
statusPagamento
dataHoraPagamento
tipoCobranca
operadorPagamento
valorPago
dataHoraAtualizacao