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ą. To kolejka Amazon SQS FIFO, jedna na lokalizację. POS otrzymuje URL kolejki, region i poświadczenia AWS podczas aktywacji. Poświadczenia pozwalają tylko odbierać i usuwać wiadomości.

Zachowanie kolejki

• Kolejność. Wiadomości są FIFO w ramach grupy wiadomości (MessageGroupId), czyli klucza porządkowania wybranego przez OpenApp. Wiadomości z różnych grup nie mają gwarancji kolejności.
• Dostarczanie at-least-once. POS może otrzymać tę samą wiadomość więcej niż raz i musi deduplikować ją po messageId.
• Visibility timeout: 30 sekund. Odebrana wiadomość pozostaje niewidoczna dla innych konsumentów przez 30 sekund. Jeśli POS jej w tym czasie nie usunie, SQS dostarczy ją ponownie.
• Zablokowane grupy. Dopóki wiadomość jest odebrana, ale nieusunięta, SQS wstrzymuje kolejne wiadomości z tej samej grupy. Wolne przetwarzanie opóźnia całą grupę.
• Retencja: 14 dni. SQS usuwa wiadomości, które pozostają w kolejce dłużej.

Koperta wiadomości kolejki

Body wiadomości to koperta JSON. messageKind i messageId są wysyłane także jako atrybuty wiadomości SQS.

Pole	Opis
messageKind	Nazwa wiadomości używana do routingu i deserializacji.
apiVersion	Wersja API wiadomości. Obecnie v1.
messageId	Unikalny ID wiadomości używany do deduplikacji i korelacji callbacka.
idempotencyKey	Klucz deduplikacji na poziomie biznesowym. Ponowienia tej samej operacji używają tej samej wartości.
payload	Ładunek specyficzny dla wiadomości.

Dla zduplikowanej komendy POS powinien zwrócić ten sam wynik biznesowy, gdy jest to możliwe.

Odbieranie wiadomości

1. Wywołuj ReceiveMessage z long pollingiem (WaitTimeSeconds: 20) przez cały czas, gdy integracja jest aktywna.
2. Pomijaj wiadomości, których messageId POS już przetworzył.
3. Przetwórz komendę.
4. Wyślij wynik do endpointu callback.
5. Wywołaj DeleteMessage z ReceiptHandle wiadomości, zależnie od odpowiedzi callbacka:

Callbacki

Po przetworzeniu wiadomości POS wysyła wynik, podpisany swoimi poświadczeniami API, na:

POST /merchant/v1/async/{messageKind}/{messageId}

Body to ładunek wyniku dla danego rodzaju wiadomości.

Odpowiedź	Znaczenie
204	Wynik przyjęty. Powtórzony callback dla już przyjętej wiadomości również zwraca 204; OpenApp ignoruje powtórzenie.
400	Body jest niepoprawne dla tego rodzaju wiadomości. Wiadomość pozostaje otwarta.
404	Wiadomość nie istnieje, należy do innego merchanta lub lokalizacji albo jej rodzaj nie pasuje do {messageKind}.

Test pełnego obiegu

Użyj wiadomości Test, aby sprawdzić odpytywanie kolejki, callbacki i usuwanie przed implementacją wiadomości biznesowych.

1. Wywołaj POST /merchant/v1/async/test, podpisane poświadczeniami POS. OpenApp zwraca { "messageId": "..." }. Poświadczenia integracji innej niż POS otrzymują 403.
2. Odbierz wiadomość Test z kolejki. Jej payload zawiera nonce.
3. Wywołaj POST /merchant/v1/async/Test/{messageId} z { "nonce": "<wartość z payloadu>" }. OpenApp zwraca 204 albo 400, jeśli nonce się nie zgadza.
4. Usuń wiadomość.

Zdarzenia inicjowane przez POS

Zdarzenia inicjowane przez POS powinny zawierać unikalny identyfikator wiadomości, aby OpenApp mógł deduplikować powtórzone dostarczenie.