Komunikacja przez kolejkę
Dostarczanie przez kolejkę jest przeznaczone dla systemów POS, które nie mogą odbierać przychodzących wywołań HTTP z OpenApp.
OpenApp posiada kolejkę i zarządza nią. System POS otrzymuje poświadczenia kolejki ograniczone do jednej funkcji integracji POS. POS odpytuje kolejkę, przetwarza pobrane wiadomości, wysyła wyniki operacji do OpenApp przez callbacki HTTP i usuwa wiadomości z kolejki po pomyślnym przetworzeniu.
Konsumenci kolejki powinni używać long pollingu. Long polling ogranicza puste odpytywanie, zmniejsza zbędny ruch sieciowy i zapobiega opóźnieniom powodowanym przez powtarzany short polling. POS powinien odpytywać kolejkę ciągle, gdy integracja jest aktywna.
Dostarczanie przez kolejkę działa w modelu at-least-once. Ta sama wiadomość może zostać dostarczona więcej niż raz, więc POS musi deduplikować komendy przy użyciu identyfikatorów wiadomości i kluczy idempotencji.
Ogólny przepływ kolejki:
Koperta wiadomości kolejki
Wiadomości kolejkowe inicjowane przez OpenApp używają wspólnej koperty. Koperta występuje w atrybutach wiadomości albo w body wiadomości.
| Pole | Opis |
|---|---|
| messageType | Logiczna nazwa wiadomości używana do routingu i deserializacji. |
| apiVersion | Wersja API używana dla tej wiadomości. |
| messageId | Unikalny ID wiadomości używany do deduplikacji dostarczania i korelacji odpowiedzi asynchronicznej. |
| idempotencyKey | Klucz deduplikacji na poziomie biznesowym. Ponowienia tej samej operacji biznesowej muszą używać tej samej wartości. |
| payload | Ładunek specyficzny dla wiadomości. |
W przepływach request/response przez kolejkę OpenApp używa messageId do korelacji żądań. Po przetworzeniu zakolejkowanej komendy POS wysyła wynik do asynchronicznego endpointu callback dla danego typu wiadomości:
POST /merchant/v1/async/{messageType}/{messageId}
Body callbacka zawiera ładunek wyniku specyficzny dla operacji. Dokładny kształt ładunku zależy od typu wiadomości.
Korelacja wiadomości i idempotencja
Każda komenda biznesowa inicjowana przez OpenApp ma unikalny identyfikator wiadomości do deduplikacji dostarczania i korelacji odpowiedzi asynchronicznej.
Ponowienia tej samej operacji biznesowej używają tego samego klucza idempotencji. POS powinien zwracać ten sam wynik biznesowy dla zduplikowanych komend, gdy jest to możliwe.
Zdarzenia inicjowane przez POS powinny również zawierać unikalny identyfikator wiadomości, aby OpenApp mógł deduplikować powtarzane dostarczenie zdarzenia.