Vendas a Bordo
Descrição dos campos associados a um evento de compra de um título a bordo do veículo.
O que é uma venda a bordo?
Venda a bordo é um evento referente a uma compra de um título de viagem já a bordo do veículo onde vai decorrer essa mesma viagem. Esse evento é transmitido como transação APEX do tipo on-board_sales, com um conjunto de campos próprios que caracterizam um evento desse tipo.
Estrutura
Campos que caracterizam um evento do tipo APEX on-board_sales:
| Nome do campo | Tipo de dado | Descrição |
|---|---|---|
| _id | GUID | Identificador único da transação de venda. |
| agency_id | Identificador único do Operador. | |
| apex_version | Versão do protocolo APEX utilizado para comunicar a transação. | |
| block_id | Identificação do plano de trabalho de um veículo. Placa - Conjunto de Circulações, Deslocações em Vazio e Tempos de Reserva cumpridos por um mesmo veículo. | |
| card_physical_type | ENUM | Tipo de suporte físico do cartão do passageiro. |
| card_serial_number | Número de série identificador do cartão associado à transação. | |
| created_at | UNIX Timestamp em milisegundos do momento em que a transação foi criada no equipamento local. | |
| device_id | GUID | Identificador único do equipamento que regista a transação APEX de venda. |
| duty_id | Identificação do plano de trabalho de um motorista/maquinista. Chapa - Conjunto de Circulações, Deslocações em Vazio e Tempos de Reserva em que intervém um mesmo motorista. | |
| is_passenger | BOL | Classifica a venda como válida ou inválida. ('true' = válida) |
| line_id | Identificador da linha em que ocorreu a transação. | |
| mac_ase_counter_value | Valor no contador de transações/eventos APEX feitos pelo cartão SAM que se encontra no equipamento que regista a venda. | |
| mac_sam_serial_number | Número de série do cartão SAM que se encontra no equipamento que regista a venda. | |
| on_board_refund_id | Identificador único do evento de reembolso associado a esta venda. | |
| pattern_id | ENUM | Código de identificação do percurso de viagem associado à venda. |
| payment_method | Modo de pagamento do título. | |
| price | STRING | Preço em céntimos de EUR, associado à transação. |
| product_long_id | NUM | Identificador do produto, ou seja, do tipo de título da viagem que está a ser vendido. |
| product_quantity | Número de unidades vendidas/carregadas no cartão referntes a esta transação. | |
| received_at | UNIX Timestamp em milisegundos do momento em que a transação foi recebida na central de base de dados. | |
| stop_id | Identificador único da paragem. | |
| trip_id | Identificador único da trip de um determinado plano de operação de um determinado operador. | |
| updated_at | UNIX Timestamp em milisegundos da última atualização dessa venda. | |
| validation_id | Identificador único da validação. | |
| vehicle_id | Identificador do veículo, unívoco por operador. |
Tudo são transações
A APEX é uma biblioteca de software que é instalada nos softwares dos validadores. É um API local que "descodifica" as mensagens que são trocadas entre os cartões navegante® e o leitor NFC do validador. A biblioteca APEX implementa o standard internacional Calypso que define o tipo de comunicações, assim como as estruturas dos dados que ficam guardados nos cartões e são processados pelos validadores.
Sempre que um cartão navegante® se encosta a um validador, é gerada uma transação. Estas transações não são mais do que ficheiros de texto que contêm todas as informações necessárias para descrever a ação que acabou de ocorrer. Por exemplo, quando um cartão navegante® toca no validador de um autocarro é gerada uma transação de validação, onde ficam registadas informações como o ID da Linha (ex: 1715), o ID do veículo, a data e hora, o número do cartão, o título utilizado para "validar" o acesso, e muitos outros dados essenciais para as equipas de gestão.
Aqui está um exemplo de uma transação de validação APEX:
{
"transactionInfo": {
"apexTransactionType": 11,
"apexTransactionVersion": "3.0",
"transactionId": "ABC-1234567890",
"transactionGroupId": "ABC-1234567890",
"transactionDate": "2025-01-01T10:15:30"
},
"versionInfo": {
"apexVersion": "3.2.6",
"vivaVersion": "1.59.2",
"technicalParametersVersion": "16.0",
"commercialOfferVersion": "116.0",
"networkVersion": "145.0",
"actionListsVersion": "5.0"
},
"operatorInfo": {
"operatorLongID": "41",
"networkID": "id-network-lisboa",
"channelID": "id-channel-val",
"deviceID": "berlioz_1234567890"
},
"cardInfo": {
"cardTypeID": "id-cardtype-lisboaviva",
"cardPhysicalType": 3,
"cardNetworkID": "id-network-lisboa",
"cardIssuer": 1,
"cardNumber": 1234567890,
"cardSerialNumber": "0000000000000000"
},
"serviceInfo": {
"blockID": "1234",
"vehicleID": 1234,
"dutyID": "1234",
"journeyID": "1234_0_1_1000_1029_0_1",
"validatorID": 2784,
"lineLongID": "1234",
"patternLongID": "1234_0_1",
"stopLongID": "123456",
"outOfBoundsType": 0,
"onBehalfOfOperatorLongID": "41"
},
"validationInfo": {
"validationType": 0,
"contractNumber": 0,
"eventType": 1,
"validationStatus": 12,
"profilesUsedCount": 0,
"profilesUsedData": [],
"greylistItemsCount": 0,
"greylistItemsData": []
},
"signedData": {
"raw": "000",
"eventBinaryRead": "000",
"eventBinaryWritten": "000",
"contractBinaryRead": "000"
},
"mac": {
"raw": "000",
"interruptedStatus": 0,
"macVersion": 4,
"binaryDataMask": 9,
"samModel": 7,
"samWorkingMode": 255,
"samTypeVersion": 2,
"fullMacFlag": 0,
"samSerialNumber": 1234567890,
"aseCounterValue": 0,
"transactionCounter": 0
}
}Existem vários tipos de transações, onde cada uma representa um tipo de ação em particular (venda de bilhete, carregamento de zapping, etc.). Cada tipo de transação tem uma estrutura própria, e todas relacionam-se entre si através de propriedades comuns.
Nesta secção vamos focar-nos nas propriedades principais dos tipos de transação principais.
O GO está intimamente relacionado com a APEX, permitindo uma enorme agilidade no consumo de todas as informações que este sistema permite. Tendo a APEX com múltiplas utilizações, foram criadas várias estruturas de dados simplificadas, que aqui documentamos, para permitir ainda mais agilidade na disponibilização de relatórios e cálculos operacionais. Estas estruturas têm as propriedades essenciais de cada um dos tipos de transações para permitir uma rápida extração de informações sobre a procura do sistema de transportes — passageiros transportados, consolidação de valores, pressão sobre determinados percursos, e muitos outros.