O que é a APEX?

A APEX é o sistema de bilhética utilizado pela Carris Metropolitana, e que está a ser implementado em todos os operadores da AML. É o que suporta todas as funcionalidades do cartão navegante® — compra e carregamentos de títulos em cartões físicos e digitais, gestão de perfis de cliente, ativação de descontos e muitas outras funcionalidades fundamentais à bilhética dos transportes públicos.

A bilhética no GO

O GO está intimamente relacionado com a APEX, permitindo uma enorme agilidade no consumo de todas as informações que um sistema de bilhética unificado torna possível. A APEX descreve o catálogo de "produtos" disponíveis num sistema de transportes: a analogia mais simples será a de uma loja online, onde é possível adquirir um enorme número de itens, cada um com uma configuração específica. Aqui o processo é exato, mas me vez de t-shirts 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.

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.