Detalhes técnicos dos ingressos do Motics na Carteira do Google

Nesta página, você encontra os detalhes técnicos que um operador de transporte público (PTO, na sigla em inglês) e o integrador de sistemas precisa se integrar ao Google para fornecer tíquetes da Motics na Carteira do Google. A solução usa a API Google Wallet e também depende na PTO implementando um endpoint de ativação.

Arquitetura do sistema

Esta seção mostra a arquitetura do sistema e o fluxo de salvamento do Motics.

Figura 1. Fluxo de salvamento de tíquetes do Motics

A Figura 1 mostra o fluxo para criar, ativar e fixar um tíquete da Motics na Carteira do Google em várias entidades:

• Servidores do Google
• Servidor de PTO (integrador de sistemas)
• Servidor SCE do Motics
• Loja on-line

Confira a seguir mais detalhes sobre o fluxo:

1. Na fase de configuração inicial, o servidor da PTO cria o transitClass, transmitir ownerId e activationUrl usando a instrução transitClass:Insert Endpoint da API Google Wallet. Esta é uma atividade única.
2. Depois, quando um usuário compra um ingresso na loja on-line, o servidor do PTO chama transitObject:Insert contendo informações básicas sobre a venda de passagens e algumas campos iniciais indicando que este é um tíquete da Motics.
3. Em seguida, o servidor do PTO e a loja on-line trabalham juntos para renderizar o Botão "Adicionar à Carteira do Google" e, por fim, retornar o JWT do tíquete para Google usando o link para salvar.
4. Agora, a fase de fixação de tíquetes pode começar, quando o servidor do Google chama o método Endpoint de ativação por trás do activationUrl.
5. Em resposta à Etapa 4, o servidor do PTO gera a assinatura (sigSTB). contendo o SCE_ID assinado com o SAM.
6. Antes de responder à chamada activationUrl, o servidor da PTO precisa chamar transitObject:Patch contendo todas as informações necessárias do Motics, incluindo o applicationData da Motics.
7. Somente após a chamada transitObject:Patch ter sido bem-sucedida, o PTO de destino deve retornar uma resposta de sucesso (HTTP-200) para o activationUrl a chamada.

Implemente a estratégia "Mover e Desvincular fluxo

Para oferecer uma boa experiência do usuário, o usuário deve ser capaz de mover seus dispositivos móveis de um dispositivo para outro, dentro de determinados limites definidos pelo emissor. Para isso, o emissor precisa implementar o fluxo para mover e desvincular.

Endpoint de ativação

O emissor/PTO (ou o integrador de sistemas) precisa implementar um tíquete o endpoint de ativação que o Google vai invocar quando o ingresso for salvo. O URL a este endpoint devem ser fornecidos na invocação de transitClass:Insert. O endpoint de ativação gera a assinatura (sigSTB) e chama o método transitObject:Patch com os parâmetros definidos no seguinte nesta seção.

Importante: o servidor do integrador de sistemas (PTO, na sigla em inglês) precisa chamar transitObject:Patch. antes de retornar do endpoint de ativação.

Solicitação

A solicitação para o endpoint de ativação tem o seguinte formato:

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

Resposta

Uma resposta HTTP-200 bem-sucedida com um corpo vazio será retornada se:

• O sigSTB contendo SCE_ID foi gerado e assinado com o SAM
• O método transitObject:Patch foi chamado com sucesso

Status: 200 - OK
Body: {}

Metas de latência

O endpoint de ativação precisa aderir às metas de latência a seguir:

• Pelo menos 50% de todas as solicitações precisam ser respondidas em 200ms.
• Pelo menos 95% de todas as solicitações precisam ser respondidas em 2s.
• Há um limite máximo fixo de 10s

Mudanças na API Google Wallet

Confira a seguir as mudanças nos endpoints da API Google Wallet para oferecer suporte a Motics, conforme descrito na arquitetura do sistema.

Importante :as etapas a seguir pressupõem que você já concluiu um Integração da API Google Wallet. Apenas as atualizações e alterações nos endpoints a O suporte para dispositivos móveis é mostrado aqui.

Método: transitClass:insert

Este é o endpoint da API Google Wallet usado para criar um transitClass no back-end. O integrador de sistemas precisa invocar essa API com o seguinte: parâmetros de solicitação junto com outros campos que são aplicáveis. Consulte a classe transitClass e transitClass.Insert para obter uma lista completa de (não móveis) e mais detalhes.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

Representação JSON

A integração do Motics requer, no mínimo, a seguinte representação JSON de o transitClass no corpo da solicitação transitClass:insert. Outro item obrigatório Os campos de metadados transitClass também precisarão ser definidos.

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

Quando certEnvironment = PRODUÇÃO, o servidor do Google buscará o certificado do servidor de produção do Motics. Quando certEnvironment = STAGING o ambiente do de busca buscará o certificado do servidor da sandbox Motics.

Método: transitObject:insert

Este é o endpoint da API Google Wallet para inserir o transitObject do novo ingresso que um usuário quer comprar e adicionar à Carteira do Google. O sistema o integrador precisa transmitir um transitObject principalmente com as informações do tíquete a este ponto. Consulte as APIs transitObject e API transitObject.Insert documentação para obter uma lista completa de parâmetros (não móveis) e mais detalhes.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitObject

Representação JSON

A integração do Motics requer, no mínimo, a seguinte representação JSON de o transitObject no corpo da solicitação transitObject:insert. Outro objeto campos de metadados também podem ser definidos e todos os outros campos obrigatórios também devem ser incluída.

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

Observações:

• A API exige que o campo applicationData esteja incluído. Neste ponto no fluxo de ativação da Motics, o valor de applicationData ainda não é conhecido, então ele precisa ser definido como uma string vazia.
  • O applicationData vai ser definido depois na transitObject:Patch a chamada.
• Os objetos DateTime validTimeInterval precisam ter a diferença de fuso horário especificado, por exemplo: 2024-04-12T19:20:50.52-04:00.

Método: transitObject:patch

Este é o endpoint da API Google Wallet para corrigir o transitObject com dados a serem usados pela geração de código de barras do Google for Motics e busca do serviço de eTicket do VDV certificados. Consulte as APIs transitObject e API transitObject.Patch documentação para obter uma lista completa de parâmetros (não móveis) e mais detalhes.

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

Representação JSON

A integração da Motics requer a seguinte representação do transitObject no corpo da solicitação transitObject:patch. Observe que ele está ponto em que o campo applicationData está preenchido.

Observação: o endpoint transitObject:patch oferece suporte à semântica de patch, portanto é suficiente para incluir somente as seguintes informações específicas da Motics quando invocando patch.

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

Especificações dos dados de aplicativos

Veja a seguir a especificação do Motics para os conteúdos dos applicationData (tag:0x5F07). O applicationData precisa ser gerado pelo o integrador de sistemas no formato tag-length-value (TLV). Esses dados são posteriores encapsulados em uma estrutura de dados maior para finalmente serem codificadas como parte do código QR o código-fonte.

Tag	Duração	Valor
0x9E	81:80	Assinatura OctetString, primeiros 128 bytes dos dados de direitos assinados Termo do Google: sigSTB
0x9A	Varia	Dados residuais OctetString, dados de direitos residuais Termo do Google: sigSTB cont.
0x7F21	81 C8	Certificado do emissor OctetString, dados do certificado Termo do Google: Cert(puk_SAM)
0x42	08	Referência da autoridade certificadora (CAR, na sigla em inglês) OctetString, valor de CAR Termo do Google: CAR