Pular para conteúdo

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:00 indicaria 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