Szczegóły techniczne biletów Motics w Portfelu Google

Na tej stronie znajdziesz szczegóły techniczne operatora transportu publicznego (PTO) oraz integrator systemów musi zintegrować go z Google, aby dostarczać bilety Motics w Portfelu Google. Rozwiązanie korzysta z interfejsu API Portfela Google i również w PTO implementującym punkt końcowy aktywacji.

Architektura systemu

Ta sekcja przedstawia architekturę systemu i proces zapisywania w Motics.

Proces – oszczędzanie biletu Motics Rysunek 1. Proces – oszczędzanie biletu Motics

Ilustracja 1 przedstawia proces tworzenia, aktywowania i przypinania zgłoszenia Motics Portfel Google w różnych usługach:

  • serwerach Google.
  • Serwer PTO (system integrator systemu)
  • Serwer SCE Motics
  • Sklep internetowy

Poniżej znajdziesz szczegółowe informacje o tym procesie:

  1. Na etapie konfiguracji początkowej serwer PTO tworzy: transitClass, przekazując ownerId i activationUrl za pomocą klasy transitClass:Insert Punkt końcowy API Portfela Google. To jednorazowa czynność.
  2. Następnie, gdy użytkownik kupuje bilet w sklepie internetowym, serwer PTO wywołuje transitObject:Insert zawierający podstawowe informacje o biletach i niektóre pola początkowe wskazujące, że jest to zgłoszenie Motics.
  3. Następnie serwer PTO i sklep internetowy współpracują nad renderowaniem Dodaj do przycisku Portfela Google, a następnie zwróć token JWT biletu do Google za pomocą linku Zapisz.
  4. Teraz może rozpocząć się faza przypinania zgłoszeń, gdy serwer Google wywoła Punkt końcowy aktywacji za punktem activationUrl.
  5. W odpowiedzi na krok 4 serwer PTO generuje podpis (sigSTB) zawierający identyfikator SCE_ID podpisany za pomocą narzędzia SAM.
  6. Zanim odpowiesz na wywołanie activationUrl, serwer PTO powinien najpierw wywołaj transitObject:Patch, który zawiera wszystkie niezbędne informacje Motics, w tym applicationData Motics.
  7. Dopiero po pomyślnym wywołaniu transitObject:Patch PTO serwer powinien zwrócić odpowiedź (HTTP-200) na żądanie activationUrl .

Ze względu na wygodę użytkowników użytkownik powinien mieć możliwość przeniesienia swoich Motics biletów z jednego urządzenia na drugie, w ramach limitów określonych przez wydawcę. W tym celu wydawca musi wdrożyć proces przenoszenia i rozłączania.

Punkt końcowy aktywacji

Wystawca lub dostawca zabezpieczeń (albo integrator systemu) musi wdrożyć zgłoszenie punkt końcowy aktywacji, który Google wywoła po zapisaniu zgłoszenia. Adres URL do tego punktu końcowego należy podać w wywołaniu transitClass:Insert. Punkt końcowy aktywacji wygeneruje podpis (sigSTB) i wywoła metodę metody transitObject:Patch z parametrami zdefiniowanymi w tym .

Żądanie

Żądanie do punktu końcowego aktywacji ma taki format:

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

Odpowiedź

Odpowiedź HTTP-200 z pustą treścią powinna być zwracana, jeśli:

  • Parametr sigSTB zawierający identyfikator SCE_ID został wygenerowany i podpisany za pomocą narzędzia SAM
  • Metoda transitObject:Patch została wywołana
Status: 200 - OK
Body: {}

Docelowe czasy oczekiwania

Punkt końcowy aktywacji powinien spełniać te wymagania dotyczące czasu oczekiwania:

  • Na co najmniej 50% z wszystkich próśb należy odpowiedzieć w ciągu 200ms
  • Na co najmniej 95% z wszystkich próśb należy odpowiedzieć w ciągu 2s
  • Istnieje stały górny limit, który wynosi 10s

Zmiany w interfejsie API Portfela Google

Poniżej opisujemy zmiany w punktach końcowych interfejsu API Portfela Google, które pozwolą Ci obsługuje platformę Motics zgodnie z architekturą systemu.

Metoda: transitClass:insert

To punkt końcowy interfejsu API Portfela Google, który pozwala utworzyć transitClass w z backendem. Integrator systemu musi wywołać ten interfejs API za pomocą: parametrów żądania i innych odpowiednich pól. Więcej informacji: transitClass oraz Dokumentacja interfejsu API transitClass.Insert z pełną listą (inne niż Motics) i więcej szczegółów.

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

Zapis JSON

Integracja z Motics wymaga co najmniej następującej reprezentacji danych JSON transitClass w treści żądania transitClass:insert. Inne obowiązkowe Trzeba też będzie określić pola metadanych transitClass.

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

Gdy parametr certEnvironment = PRODUCTION, serwer Google pobierze certyfikat. z serwera produkcyjnego Motics. Gdy certEnvironment = STAGing the Google serwer pobierze certyfikat z serwera Motics w piaskownicy.

Metoda: transitObject:insert

To jest punkt końcowy interfejsu API Portfela Google, w którym należy wstawić transitObject dla nowego bilet, który użytkownik chce kupić i dodać do Portfela Google. System integrator powinien przekazać transitObject z informacjami o biletach w w tym punkcie. Zapoznaj się z obiektami transitObject i Interfejs API transitObject.Insert dokumentację z pełną listą parametrów (innych niż Motics) i dodatkowymi informacjami.

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

Zapis JSON

Integracja z Motics wymaga co najmniej następującej reprezentacji danych JSON transitObject w treści żądania transitObject:insert. Inny obiekt Można też skonfigurować pola metadanych i wypełnić wszystkie pozostałe wymagane pola. dołączono.

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

Uwagi:

  • Interfejs API wymaga uwzględnienia pola applicationData. W tym momencie w procesie aktywacji Motics wartość applicationData nie jest jeszcze znana, więc jako wartość musisz wpisać pusty ciąg znaków.
    • applicationData zostanie ustawione później w transitObject:Patch .
  • Obiekty DateTime validTimeInterval muszą mieć przesunięcie strefy czasowej określony, na przykład: 2024-04-12T19:20:50.52-04:00.

Metoda: transitObject:patch

To punkt końcowy interfejsu API Portfela Google, który ma zainstalować poprawkę transitObject za pomocą danych używane przez Google do generowania kodów kreskowych Motics i pobierania z usługi VDV eTicket certyfikatów. Zapoznaj się z obiektami transitObject i Interfejs API transitObject.Patch dokumentację z pełną listą parametrów (innych niż Motics) i dodatkowymi informacjami.

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

Zapis JSON

Integracja z Motics wymaga następującej reprezentacji funkcji transitObject w treści żądania: transitObject:patch. Zwróć uwagę, że jest to wskazuje, że pole applicationData jest wypełnione.

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

Specyfikacja danych aplikacji

Poniżej specyfikacja Motics dla zawartości applicationData (tag:0x5F07). Wartość applicationData powinna zostać wygenerowana do z integratora systemu w formacie TLV (tag-długość tagu). Te dane są późniejsze w większej strukturze danych do zakodowania na końcu jako część kodu QR w kodzie.

Tag Długość Wartość
0x9E 81 80 Podpis
OctetString, pierwsze 128 bajtów podpisanych danych dotyczących uprawnień
Hasło wyszukiwane przez Google: sigSTB
0x9A W zależności od usługi Dane resztowe
OctetString, dane pozostałych upoważnień
Hasło wyszukiwane przez Google: sigSTB cont.
0x7F21 81 C8 Certyfikat wydający
OctetString, dane certyfikatu
Hasło wyszukiwane przez Google: Cert(puk_SAM)
0x42 08 Numer referencyjny urzędu certyfikacji (CAR)
OctetString, wartość CAR:
Hasło wyszukiwane przez Google: CAR