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.

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 .

Wdrożenie funkcji Odłącz proces

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 .

Ważne: serwer PTO (integrator systemu) musi wywołać metodę transitObject:Patch zanim wrócisz z punktu końcowego aktywacji.

Żą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.

Ważne: w poniższym przykładzie zakładamy, że masz już ukończony standardowy Integracja interfejsu API Portfela Google. Tylko aktualizacje i zmiany punktów końcowych na pomocy Motics można znaleźć tutaj.

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.

Uwaga: punkt końcowy transitObject:patch obsługuje semantykę poprawki, więc jest wystarczają do podania konkretnych informacji z firmy Motics tylko wtedy, gdy wywołując poprawkę.

{
  "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