Detalles técnicos de las entradas para Motics en la Billetera de Google

En esta página, se proporcionan los detalles técnicos de un operador de transporte público (PTO) y el integrador de sistemas debe integrarse con Google para proporcionar los tickets de Motics en la Billetera de Google. La solución utiliza la API de la Billetera de Google y también se basa en la PTO con la implementación de un extremo de activación.

Arquitectura del sistema

En esta sección, se muestra la arquitectura del sistema y el flujo de guardado de Motics.

Flujo para guardar entradas de Motics Figura 1: Flujo para guardar entradas de Motics

La Figura 1 muestra el flujo para crear, activar y fijar un ticket de Motics en Billetera de Google en varias entidades:

  • Servidores de Google
  • Servidor de PTO (integrador de sistemas)
  • Servidor SCE de Motics
  • Tienda web

A continuación, se describe el flujo con más detalle:

  1. En la fase de configuración inicial, el servidor PTO crea transitClass, pasando ownerId y activationUrl con transitClass:Insert extremo de la API de la Billetera de Google. Esta actividad se realiza una sola vez.
  2. Luego, cuando un usuario compra un ticket en la tienda web, el servidor PTO llama transitObject:Insert contiene información básica sobre los tickets y algo de campos iniciales que indican que se trata de un ticket de Motics.
  3. Luego, el servidor de PTO y la tienda web trabajan juntos para renderizar Botón Agregar a la Billetera de Google y, en última instancia, devuelve el JWT del ticket a Google, a través del vínculo de guardado.
  4. Ahora puede comenzar la fase de fijación de tickets, cuando el servidor de Google llama Extremo de activación detrás de activationUrl.
  5. En respuesta al paso 4, el servidor PTO genera la firma (sigSTB). que contenga el SCE_ID firmado con el SAM.
  6. Antes de responder a la llamada a activationUrl, el servidor de PTO debe hacerlo llamar a transitObject:Patch, que contiene toda la información de Motics necesaria, incluido applicationData de Motics.
  7. Solo después de que la llamada a transitObject:Patch se realice de forma correcta, la PTO el servidor debe mostrar una respuesta correcta (HTTP-200) al activationUrl llamada.

Para proporcionar una buena experiencia del usuario, el usuario debe poder mover sus Motics. boleto de un dispositivo a otro, dentro de ciertos límites definidos por la entidad emisora. Para ello, la entidad emisora debe implementar el flujo de migración y desvinculación.

Extremo de activación

La entidad emisora o la PTO (o su integrador de sistemas) debe implementar un ticket de activación que Google invocará cuando se guarde el ticket. La URL a este extremo se deben proporcionar en la invocación de transitClass:Insert. El extremo de activación generará la firma (sigSTB) y llamará al transitObject:Patch con los parámetros definidos a continuación sección.

Solicitud

La solicitud al extremo de activación tiene el siguiente 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,
}

Respuesta

Se debería mostrar una respuesta exitosa HTTP-200 con un cuerpo vacío en los siguientes casos:

  • El sigSTB que contiene SCE_ID se generó y se firmó con el SAM
  • Se llamó correctamente al método transitObject:Patch
Status: 200 - OK
Body: {}

Objetivos de latencia

El extremo de activación debe cumplir con los siguientes objetivos de latencia:

  • Se debe responder, al menos, el 50% de todas las solicitudes en un plazo de 200ms
  • Se debe responder, al menos, el 95% de todas las solicitudes en un plazo de 2s
  • Hay un límite máximo estricto de 10s

Cambios en la API de la Billetera de Google

A continuación, se describen los cambios en los extremos de la API de la Billetera de Google para lo siguiente: admitir Motics como se describe en la arquitectura del sistema.

Método: transitClass:insert

Este es el extremo de la API de la Billetera de Google para crear un transitClass en el backend. El integrador de sistemas debe invocar esta API con lo siguiente: los parámetros de solicitud junto con cualquier otro campo que sea aplicable. Consulta la transitClass y transitClass.Insert para obtener una lista completa de (no Motics) y más detalles.

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

Representación JSON

La integración de Motics requiere como mínimo la siguiente representación JSON de el transitClass en el cuerpo de la solicitud transitClass:insert. Otro obligatorio También se deberán configurar transitClass campos de metadatos.

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

Cuando certEnvironment = PRODUCTION, el servidor de Google recuperará el certificado del servidor de producción de Motics. Cuando certEnvironment = STAGING el servidor recuperará el certificado del servidor de Motics de la zona de pruebas.

Método: transitObject:insert

Este es el extremo de la API de la Billetera de Google para insertar el transitObject para el nuevo entrada que un usuario quiere comprar y agregar a la Billetera de Google. El sistema El integrador debe pasar un transitObject que contenga, principalmente, la información del ticket en este punto. Consulta transitObject y API de transitObject.Insert para obtener una lista completa de los parámetros (no Motics) y más detalles.

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

Representación JSON

La integración de Motics requiere como mínimo la siguiente representación JSON de el transitObject en el cuerpo de la solicitud transitObject:insert. Otro objeto campos de metadatos y todos los demás campos obligatorios también deben incluidos.

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

Notas:

  • La API requiere que se incluya el campo applicationData. En este punto En el flujo de activación de Motics, aún no se conoce el valor applicationData. por lo que debe configurarse como una cadena vacía.
    • El applicationData se configurará más adelante en el transitObject:Patch llamada.
  • Los objetos de fecha y hora validTimeInterval deben tener el desplazamiento de zona horaria especificado, por ejemplo: 2024-04-12T19:20:50.52-04:00.

Método: transitObject:patch

Este es el extremo de la API de la Billetera de Google para aplicar un parche a transitObject con datos que se usado por Google para la generación de códigos de barras de Motics y para recuperar el servicio de boletos electrónicos de VDV certificados. Consulta transitObject y API de transitObject.Patch para obtener una lista completa de los parámetros (no Motics) y más detalles.

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

Representación JSON

La integración de Motics requiere la siguiente representación del transitObject en el cuerpo de la solicitud transitObject:patch. Ten en cuenta que es aquí el punto en el que se propaga el campo applicationData.

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

Especificaciones de los datos de aplicación

A continuación, se detalla la especificación de Motics para el contenido de la applicationData (etiqueta:0x5F07). El applicationData debe generarse por el integrador de sistemas en formato tag-length-value (TLV). Estos datos son posteriores en una estructura de datos más grande para que se codifique como parte del código QR código.

Etiqueta Longitud Valor
0x9E 81 x 80 Firma
OctetString, primeros 128 bytes de datos de derechos firmados
Término de Google: sigSTB
0x9A Varía Datos residuales
OctetString, datos residuales de derechos
Término de Google: sigSTB cont.
0x7F21 81 C8 Certificado del emisor
OctetString, datos del certificado
Término de Google: Cert(puk_SAM)
0x42 08 Referencia de autoridad certificadora (CAR)
OctetString, valor del CAR
Término de Google: CAR