Технические детали билетов Motics в Google Кошельке

На этой странице представлены технические подробности, которые оператору общественного транспорта (PTO) и его системному интегратору необходимо интегрировать с Google для предоставления билетов Motics в Google Кошельке. Решение использует API Google Кошелька, а также опирается на PTO, реализующий конечную точку активации.

Архитектура системы

В этом разделе показана архитектура системы и процесс сохранения Motics.

Сохранить поток билетов Motics Рисунок 1. Процесс сохранения заявки Motics

На рис. 1 показан процесс создания, активации и закрепления билета Motics в Google Кошельке в нескольких объектах:

  • Серверы Google
  • Сервер PTO (системный интегратор)
  • Сервер Motics SCE
  • Интернет-магазин

Ниже описывается поток более подробно:

  1. На начальном этапе настройки сервер PTO создает transitClass , передавая ownerId activationUrl с помощью TransitClass:Insert конечную точку API Google Кошелька. Это разовое мероприятие.
  2. Затем, когда пользователь покупает билет в интернет-магазине, сервер PTO вызываетtransitObject :Insert, содержащий основную информацию о билете и некоторые начальные поля, указывающие, что это билет Motics.
  3. Затем сервер PTO и интернет-магазин работают вместе, чтобы отобразить кнопку «Добавить в Google Кошелек» и в конечном итоге вернуть JWT билета в Google, используя ссылку для сохранения.
  4. Теперь может начаться этап закрепления билета, когда сервер Google вызывает конечную точку активации за activationUrl .
  5. В ответ на шаг 4 сервер PTO генерирует подпись (sigSTB), содержащую SCE_ID, подписанный с помощью SAM.
  6. Прежде чем ответить на вызов activationUrl , сервер PTO должен сначала вызвать TransitObject:Patch, содержащий всю необходимую информацию Motics, включая applicationData Motics.
  7. Только после успешного вызова TransitObject:Patch сервер PTO должен вернуть успешный ответ (HTTP-200) на вызов activationUrl .

Чтобы обеспечить удобство использования, пользователь должен иметь возможность переносить свой билет Motics с одного устройства на другое в пределах определенных ограничений, определенных эмитентом. Для этого эмитенту необходимо реализовать Move and Unlink Flow .

Конечная точка активации

Эмитент/PTO (или его системный интегратор) должен реализовать конечную точку активации билета, которую Google будет вызывать при сохранении билета. URL-адрес этой конечной точки должен быть указан при вызове TransitClass:Insert . Конечная точка активации сгенерирует подпись (sigSTB) и вызовет метод TransitObject:Patch с параметрами, определенными в следующем разделе.

Запрос

Запрос к конечной точке активации имеет следующий формат:

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,
}

Ответ

Ответ об успешном завершении HTTP-200 с пустым телом должен быть возвращен, если:

  • sigSTB, содержащий SCE_ID, был создан и подписан SAM.
  • Метод TransitObject:Patch был успешно вызван. 
Status: 200 - OK
Body: {}

Целевые значения задержки

Конечная точка активации должна соответствовать следующим целевым показателям задержки:

  • По крайней мере, 50% всех запросов необходимо ответить в течение 200ms
  • По крайней мере, 95% всех запросов должны быть обработаны в течение 2s
  • Существует жесткий верхний предел в 10s

Изменения API Google Кошелька

Ниже описаны изменения в конечных точках API Google Кошелька для поддержки Motics, как указано в архитектуре системы.

Метод: транзитКласс:вставить

Это конечная точка API Google Кошелька для создания transitClass на серверной части Google. Системному интегратору необходимо вызвать этот API со следующими параметрами запроса и любыми другими применимыми полями. Полный список параметров (не Motics) и более подробную информацию см. в документации по API TransitClass и TransitClass.Insert .

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

JSON-представление

Для интеграции Motics требуется как минимум следующее JSON-представление transitClass в теле запроса transitClass:insert . Также необходимо будет установить другие обязательные поля метаданных transitClass .

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

Если certEnvironment = PRODUCTION, сервер Google получит сертификат с рабочего сервера Motics. Когда certEnvironment = STAGING, сервер Google получит сертификат с изолированного сервера Motics.

Метод: транзитОбъект:вставить

Это конечная точка API Google Кошелька, позволяющая вставить transitObject для нового билета, который пользователь хочет приобрести и добавить в Google Кошелек. На этом этапе системный интегратор должен передать transitObject , в основном содержащий информацию о билете. Полный список параметров (не Motics) и более подробную информацию см. в документации по API TransitObject и TransitObject.Insert .

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

JSON-представление

Для интеграции Motics требуется как минимум следующее представление transitObject в формате JSON в теле запроса transitObject:insert . Другие поля метаданных объекта также могут быть установлены, и все остальные обязательные поля также должны быть включены.

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

Примечания:

  • API требует включения поля applicationData . На этом этапе процесса активации Motics значение applicationData еще не известно, поэтому для него необходимо задать пустую строку.
    • applicationData будет установлен позже при вызове transitObject:Patch .
  • Для объектов validTimeInterval DateTime должно быть указано смещение часового пояса, например: 2024-04-12T19:20:50.52-04:00 .

Метод: транзитОбъект:patch

Это конечная точка API Google Кошелька для внесения в transitObject данных, которые будут использоваться Google для создания штрих-кода Motics и получения сертификатов службы электронных билетов VDV. Полный список параметров (не Motics) и более подробную информацию см. в документации API TransitObject и TransitObject.Patch .

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

JSON-представление

Для интеграции Motics требуется следующее представление transitObject в тексте запроса transitObject:patch . Обратите внимание, что именно в этот момент заполняется поле applicationData .

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

Характеристики данных приложения

Ниже приведена спецификация Motics для содержимого applicationData (тег: 0x5F07 ). applicationData должны быть сгенерированы системным интегратором в формате значения длины тега (TLV). Эти данные позже инкапсулируются в более крупную структуру данных и окончательно закодируются как часть QR-кода.

Ярлык Длина Ценить
0x9E 81 80 Подпись
OctetString , первые 128 байт подписанных данных о правах.
Google-термин: sigSTB
0x9A Варьируется Остаточные данные
OctetString , остаточные данные о правах
Термин Google: sigSTB cont.
0x7F21 81 С8 Сертификат о выдаче
OctetString , данные сертификата
Термин Google: Cert(puk_SAM)
0x42 08 Ссылка на центр сертификации (CAR)
OctetString , значение CAR
Термин Google: CAR