Linkowanie odbiorcy napiwku
Przepływ linkowania odbiorcy napiwku pozwala pracownikowi połączyć swoje konto OpenApp z identyfikatorem z POS. Merchant API nazywa ten identyfikator externalTipRecipientId. Komunikaty płatności i kody QR paragonu używają krótszej nazwy tipRecipientId dla tej samej wartości.
Po potwierdzeniu linku w OpenApp i przejściu KYC rekord staje się ACTIVE. Napiwki przypisane do jego externalTipRecipientId są wtedy kierowane do portfela OpenApp pracownika. Jeśli rekord nie istnieje albo nie jest aktywny, napiwki trafiają do rozliczenia merchanta.
POS jest odpowiedzialny za zebranie numeru telefonu, który pracownik chce powiązać. Sposób, w jaki POS prezentuje to użytkownikowi, leży w jego gestii.
Endpointy używane w tym przepływie:
| Endpoint | Kierunek | Cel |
|---|---|---|
GET /merchant/v1/tipRecipients | POS -> OpenApp | Pobierz wszystkie rekordy odbiorców napiwku w zakresie merchanta i profilu integracji powiązanym z poświadczeniami API. |
GET /merchant/v1/tipRecipients/{id} | POS -> OpenApp | Pobierz rekord, którego externalTipRecipientId jest równe {id}. |
PUT /merchant/v1/tipRecipients/{id} | POS -> OpenApp | Wykonaj upsert rekordu i, gdy jest to potrzebne, rozpocznij linkowanie konta. Treść żądania: PutTipRecipientRequest. Odpowiedź: LinkTipRecipientResponse. |
Wszystkie trzy endpointy używają uwierzytelniania HMAC Merchant API. OpenApp ustala zakres merchanta i profilu integracji na podstawie poświadczeń API; POS nie wysyła żadnego z tych identyfikatorów w żądaniu.
Identyfikatory
Każdy rekord ma dwa identyfikatory:
externalTipRecipientIdto stabilny identyfikator podawany przez POS jako parametr ścieżki{id}. Komunikaty płatności i kody QR paragonu odnoszą się do tej wartości jakotipRecipientId.idto identyfikator wygenerowany przez OpenApp, zwracany w odpowiedzi API. Aplikacja OpenApp używa go podczas potwierdzenia. POS powinien nadal adresować rekord przezexternalTipRecipientId.
Odczyt listy odbiorców
POS może pobrać aktualną listę odbiorców w dowolnym momencie, aby wypełnić interfejs wyboru pracownika albo zweryfikować rekordy.
GET /merchant/v1/tipRecipients zwraca tablicę rekordów TipRecipient.
GET /merchant/v1/tipRecipients/{id} zwraca jeden rekord TipRecipient albo HTTP 404, jeśli externalTipRecipientId nie istnieje w zakresie poświadczeń.
Zgłoszenie linkowania
POS wysyła PUT /merchant/v1/tipRecipients/{id} z numerem telefonu i nazwą wyświetlaną pracownika. OpenApp normalizuje numer telefonu i stosuje następujące reguły:
| Aktualny rekord | Wynik |
|---|---|
| Brak rekordu | OpenApp tworzy rekord PENDING z trzydniowym okresem potwierdzenia. |
PENDING | OpenApp aktualizuje numer telefonu i nazwę wyświetlaną oraz rozpoczyna od nowa trzydniowy okres potwierdzenia. |
ACTIVE | OpenApp usuwa aktualne powiązanie użytkownika, zmienia rekord na PENDING i rozpoczyna nowy trzydniowy okres potwierdzenia. |
Odpowiedź zawsze zawiera wynikowy rekord w LinkTipRecipientResponse.tipRecipient. Błędy walidacji używają standardowych odpowiedzi błędów HTTP, a nie wyniku sukcesu albo błędu specyficznego dla przepływu.
Zobacz PutTipRecipientRequest po pełną referencję treści żądania.
Potwierdzenie i status
Dla rekordu PENDING OpenApp powiadamia pracownika, gdy konto OpenApp już istnieje dla przesłanego numeru telefonu. Pracownik potwierdza link w aplikacji OpenApp. Potwierdzenie wymaga tego samego numeru telefonu oraz konta, które spełnia wymóg KYC OpenApp.
POS może odpytywać dowolny z endpointów GET i sprawdzać linkStatus. Gdy status to PENDING, expiresAt podaje termin potwierdzenia. OpenApp odrzuca potwierdzenie po tym terminie. Usunięcie wygasłego rekordu jest asynchroniczne, więc GET może przez chwilę zwrócić wygasły rekord PENDING. Wyślij kolejne PUT, aby rozpocząć proces od nowa.
Zobacz Link status po pełny słownik statusów.
Po stronie POS nie ma endpointu do odlinkowania. Przesłanie innego numeru telefonu dla aktywnego rekordu zastępuje aktualne powiązanie nowym oczekującym linkiem.