Przejdź do głównej zawartości

Modele danych

Ta strona jest referencją dla wszystkich wiadomości integracji POS, wspólnych modeli bazowych i enumów.

Modele oznaczone jako TBD nie są jeszcze sfinalizowane w kontrakcie integracji i mogą zmienić się przed ogólną dostępnością.

Wiadomości aktywacji​

ActivatePos​

Wysyłane przez POS do POST /merchant/v1/pos/activate.

merchantTaxIdstringWymagane

Uniwersalny identyfikator podatkowy merchanta, na przykład polski NIP.

pinCodestringWymagane

Krótkotrwały PIN aktywacyjny wyświetlany w panelu merchanta.

posInstallationIdstringOpcjonalne

Stabilny identyfikator instalacji POS po stronie merchanta.

softwareNamestringWymagane

Nazwa produktu oprogramowania POS.

softwareVersionstringWymagane

Ciąg wersji oprogramowania POS.

PosActivationResponse​

Zwracane przez OpenApp w odpowiedzi na ActivatePos, zawsze z HTTP 200.

successbooleanWymagane

true.

merchantIdstringWymagane

Identyfikator merchanta ustalony z merchantTaxId.

integrationProfileIdstringWymagane

Profil integracji ograniczony do lokalizacji, z którym POS jest teraz powiązany.

apiConfigurationobjectWymagane

Obiekt z credentials (apiKey, secret) używanymi do podpisywania wywołań POS -> OpenApp.

queueConfigurationobjectWymagane

Obiekt z queueUrl, region, accessKeyId i secretAccessKey. Poświadczenia AWS pozwalają tylko odbierać i usuwać wiadomości z tej kolejki POS.

ReportPosHealth​

Wysyłane przez POS bezpośrednio po aktywacji i w regularnych interwałach heartbeat. OpenApp odpowiada HTTP 204 No Content.

Jeśli OpenApp nie otrzyma sprawdzeń stanu w czasie skonfigurowanym w profilu integracji, OpenApp oznacza funkcję POS jako niedostępną, przestaje wysyłać komendy zamówień obsługiwane przez POS i informuje klientów, że lokalizacja jest obecnie niedostępna.

healthybooleanWymagane

Aktualny stan zdrowia POS.

softwareNamestringWymagane

Nazwa produktu oprogramowania POS.

softwareVersionstringWymagane

Ciąg wersji oprogramowania POS.

Wiadomości kontroli dostępności​

PosLocationAvailabilityChanged​

Wysyłane przez POS, gdy lokalizacja jest otwierana lub zamykana dla zamówień obsługiwanych przez OpenApp. Zamknięcie lokalizacji wyłącza nowe zamówienia przy stoliku, zamówienia na odbiór i zamówienia z dostawą do czasu ponownego otwarcia przez POS albo otrzymania przez OpenApp równoważnej aktualizacji dostępności z innego autoryzowanego źródła.

openbooleanWymagane

true, gdy lokalizacja jest otwarta dla zamówień obsługiwanych przez OpenApp; false, gdy jest zamknięta.

reasonCodestringOpcjonalne

Powód czytelny maszynowo, na przykład CLOSED_FOR_DAY, TEMPORARILY_CLOSED albo POS_OPERATOR_ACTION.

messagestringOpcjonalne

Komunikat czytelny dla człowieka, który OpenApp może mapować na treść widoczną dla klienta.

effectiveAtstringOpcjonalne

Znacznik czasu ISO 8601, od którego stan zaczyna obowiązywać. Domyślnie czas otrzymania.

PosOrderTypeAvailabilityChanged​

Wysyłane przez POS, gdy chce zmienić dostępność wybranych typów zamówień obsługiwanych przez OpenApp bez zamykania lokalizacji. Obsługuje to tymczasową kontrolę obciążenia, na przykład wstrzymanie odbioru i dostawy w godzinach szczytu przy pozostawieniu aktywnego zamawiania przy stanowisku (stoliku).

Dostępność STATION ogranicza tylko zamawianie przy stoliku.

changesarray of objectsWymagane

Lista zmian dostępności typów zamówień. Zmieniane są tylko wymienione typy zamówień; pominięte typy pozostają bez zmian. Każdy element zawiera orderType, state, opcjonalne reasonCode i opcjonalne effectiveUntil.

Pokaż parametry podrzędneUkryj parametry podrzędne4
orderTypeOrderTypeWymagane

Typ zamówienia do zmiany. Zobacz Order types.

stateOrderTypeAvailabilityStateWymagane

Docelowy stan tego typu zamówienia. Zobacz Order type availability states.

reasonCodestringOpcjonalne

Powód stanu tego typu zamówienia czytelny maszynowo, na przykład KITCHEN_OVERLOADED, NO_DRIVERS.

effectiveUntilstringOpcjonalne

Znacznik czasu ISO 8601, po którym OpenApp może wyczyścić stan tego typu zamówienia. Jeśli pominięte, stan pozostaje do kolejnej zmiany.

Przykład:

{
  "changes": [
    {
      "orderType": "PICKUP",
      "state": "PAUSED",
      "reasonCode": "KITCHEN_OVERLOADED",
      "effectiveUntil": "2026-05-29T18:00:00Z"
    },
    {
      "orderType": "DELIVERY",
      "state": "PAUSED",
      "reasonCode": "NO_DRIVERS",
      "effectiveUntil": "2026-05-29T19:00:00Z"
    }
  ]
}

Wiadomości synchronizacji menu​

ProductListingsSyncRequested​

checkpointobject | nullWymagane

Ostatni punkt kontrolny synchronizacji. null żąda pełnej synchronizacji. Obiekt zawiera znacznik czasu ostatniego pomyślnego pobrania i ostatni widziany identyfikator listingu POS.

ProductListingsSynced​

checkpointobjectWymagane

Następny punkt kontrolny do użycia w kolejnych synchronizacjach przyrostowych.

listingsarrayWymagane

Listingi produktów zmienione po żądanym punkcie kontrolnym. Puste, gdy nic się nie zmieniło.

ProductListingsUpdated​

listingsarrayWymagane

Zmienione dane listingu produktu, ceny albo stanu magazynowego. Zawiera tylko różnicę.

Wiadomości zamawiania przy stoliku​

TableOrderSnapshotRequested​

tableIdstringWymagane

Identyfikator stolika POS ustalony przez OpenApp z QR.

checkpointstringOpcjonalne

Ostatni znacznik czasu aktualizacji POS zapisany przez OpenApp dla tego stolika. POS może go użyć, aby zdecydować, czy zwrócić snapshot.

TableOrderSnapshotResolutionResult​

Zwracane przez POS w odpowiedzi na TableOrderSnapshotRequested.

successbooleanWymagane

true.

tableSessionContextobjectWymagane

Zobacz tableSessionContext.

tableOrderSnapshotobjectWymagane

Zobacz tableOrderSnapshot.

OrderSubmissionRequested​

Wysyła pozycje dla kontekstu realizacji STATION, PICKUP albo DELIVERY.

Gdy payment jest obecne, OpenApp już zakończył płatność klienta, a wysłanie jest prepaid. Gdy payment jest pominięte, wysłanie jest nieopłacone/postpaid, a płatność jest obsługiwana później poza tą wiadomością.

orderContextobjectWymagane

Zobacz orderContext.

itemsarrayWymagane

Pozycje wysyłane do POS. TBD

paymentobjectOpcjonalne

Zakończona płatność OpenApp dla wysłań prepaid. Pomiń dla wysłań nieopłaconych/postpaid. Zobacz payment.

OrderSubmissionResult​

Zwracane przez POS w odpowiedzi na OrderSubmissionRequested. Używane przez konteksty stolika, odbioru i dostawy.

success: false jest też używane, gdy odrzucono tylko część pozycji.

successbooleanWymagane

true. Wszystkie wysłane pozycje zostały zaakceptowane.

acceptedItemsarrayWymagane

Pozycje zaakceptowane przez POS. TBD

tableOrderSnapshotobjectOpcjonalne

Zaktualizowany snapshot stolika POS. Tylko przepływ stolika. Zobacz tableOrderSnapshot.

receiptobjectOpcjonalne

Paragon albo potwierdzenie fiskalne dla wysłań prepaid, gdy OrderSubmissionRequested.payment było obecne. Zobacz receipt.

TableOrderSnapshotChanged​

Wysyłane przez POS, gdy stan zamówienia stolika zmienia się po stronie POS.

changeTypestringWymagane

Zobacz Change types.

diffobjectWymagane

Zmienione linie zamówienia, usunięte identyfikatory linii i zmiany statusu względem poprzedniego snapshotu. TBD

reasonCodestringOpcjonalne

Wymagane, gdy zmiana ma powód biznesowy. Na przykład brak towaru, reklamacja albo anulowanie po stronie POS.

Wiadomości rachunku i płatności​

BillPreparationRequested​

orderContextobjectWymagane

Identyfikuje stanowisko albo zamówienie. Zobacz orderContext.

checkpointstringOpcjonalne

Najnowszy checkpoint stanu po stronie POS, który posiada OpenApp. Dla kontekstów sesji stolika jest to updatedAt z najnowszego tableOrderSnapshot; POS używa go, aby zdecydować, czy zwrócić ORDER_CHANGED. Pomijany dla przepływów bezstanowych, takich jak Scan & Pay, gdzie OpenApp nie posiada poprzedniego stanu. Znacznik czasu ISO 8601.

itemsarrayOpcjonalne

Pozycje do rozliczenia. Obecne, gdy opłacana jest tylko część zamówienia. Odwołuje się do istniejących identyfikatorów pozycji po stronie POS z tableOrderSnapshot.lines. Format selektora jest TBD razem ze schematem identyfikatorów pozycji w tableOrderSnapshot.lines.

BillPreparationResult​

Zwracane przez POS w odpowiedzi na BillPreparationRequested.

successbooleanWymagane

true.

billobjectWymagane

Zobacz bill.

tipRecipientIdstringOpcjonalne

Identyfikator odbiorcy napiwku po stronie POS dla tego stanowiska. Jest to ta sama wartość co TipRecipient.externalTipRecipientId. OpenApp używa go do przypisania napiwku. Gdy klient zeskanował kod QR z paragonu z zakodowanym odbiorcą napiwku (zobacz Scan & Pay - Budowanie kodu QR na paragon), ta wartość ma pierwszeństwo, a to pole jest ignorowane.

BillPaymentCompleted​

Używane, gdy płatność OpenApp następuje po przygotowaniu rachunku przez POS.

paymentobjectWymagane

Szczegóły płatności do zarejestrowania. Zobacz payment.

posBillIdstringWymagane

Identyfikator nadany przez POS i zwrócony w BillPreparationResult.bill.

billingDetailsobjectOpcjonalne

Dane faktury. Zobacz billingDetails.

BillPaymentFailed​

Wysyłane tylko wtedy, gdy płatność OpenApp nie powiedzie się po pomyślnym BillPreparationResult. Wysłania prepaid nigdy nie wywołują BillPaymentFailed, ponieważ OpenApp wykonuje płatność przed kontaktem z POS; jeśli płatność się nie powiedzie, OpenApp nie wysyła zamówienia.

posBillIdstringWymagane

Identyfikator nadany przez POS i zwrócony w BillPreparationResult.bill.

reasonCodestringWymagane

Powód niepowodzenia czytelny maszynowo. POS zwalnia każdy przygotowany albo oczekujący na płatność stan.

BillPaymentResult​

Zwracane przez POS w odpowiedzi na BillPaymentCompleted dla późniejszej płatności OpenApp dotyczącej przygotowanego rachunku. Nie jest używane dla wysłań prepaid, w których payment było zawarte w OrderSubmissionRequested.

successbooleanWymagane

true.

receiptobjectWymagane

Zobacz receipt.

Modele bazowe​

orderContext​

Identyfikuje kontekst realizacji po stronie POS, którego dotyczy komenda.

typestringWymagane

STATION. Kontekst zamówienia na stanowisku - obejmuje zarówno stanowiska stolikowe, jak i kioskowe.

stationIdstringWymagane

Identyfikator stanowiska POS ustalony przez OpenApp z kodu QR stanowiska.

stationKindstringWymagane

Rodzaj stanowiska. TABLE dla stanowiska stolikowego; KIOSK dla stanowiska kioskowego.

customerNotestringOpcjonalne

Notatka tekstowa widoczna dla POS.

tableSessionContext​

Metadane sesji stolika zwracane razem ze snapshotami stolika, gdy stolik zostanie rozwiązany.

locationIdstringWymagane

Fizyczna lokalizacja restauracji.

tableIdstringWymagane

Identyfikator stolika POS.

tableNumberstringWymagane

Numer stolika czytelny dla człowieka.

statusstringWymagane

Zobacz Table status.

openedAtstringWymagane

Znacznik czasu ISO 8601 otwarcia stolika.

closedAtstringOpcjonalne

Znacznik czasu ISO 8601 zamknięcia stolika. Obecny, gdy status to closed albo cancelled.

tableOrderSnapshot​

POS pozostaje źródłem prawdy dla stanu stolika/otwartego rachunku. OpenApp mapuje istotny stan do widoków klienckich.

tableIdstringWymagane

Identyfikator stolika POS.

statusstringWymagane

Zobacz Table status.

linesarrayWymagane

Linie zamówienia POS. TBD

totalsobjectWymagane

Sumy rachunku. TBD

paymentsarrayWymagane

Płatności zastosowane w POS. TBD

updatedAtstringWymagane

Znacznik czasu ISO 8601 ostatniej aktualizacji POS. Używany przez OpenApp jako następny punkt kontrolny synchronizacji.

billingDetails​

Dane faktury dołączone do rachunku, gdy klient prosi o fakturę. TBD

taxIdstringWymagane

Identyfikator podatkowy podmiotu fakturowanego, na przykład polski NIP.

companyNamestringWymagane

Nazwa prawna na fakturze.

addressobjectWymagane

Adres pocztowy. TBD

bill​

Zwracane przez POS w BillPreparationResult, gdy rachunek zostanie przygotowany. TBD

posBillIdstringWymagane

Identyfikator przygotowanego rachunku nadany przez POS.

linesarrayOpcjonalne

Linie rachunku zamrożone przez POS. Opcjonalne - POS może zwrócić rachunek zawierający tylko sumę, gdy szczegółowe dane pozycji są niedostępne albo niewymagane. TBD

totalsobjectWymagane

Sumy rachunku. TBD

preparedAtstringWymagane

Znacznik czasu ISO 8601 przygotowania i zamrożenia rachunku.

payment​

Szczegóły pomyślnej płatności OpenApp.TBD

oaPaymentIdstringWymagane

Identyfikator płatności OpenApp.

amountobjectWymagane

Obiekt pieniędzy z value (integer, jednostki mniejsze) i currency (string). TBD

paidAtstringWymagane

Znacznik czasu ISO 8601 zakończenia płatności.

receipt​

Zwracane przez POS po zarejestrowaniu albo zastosowaniu płatności OpenApp. TBD

receiptNumberstringWymagane

Numer paragonu nadany przez POS.

fiscalSignaturestringOpcjonalne

Podpis fiskalizacji, jeśli dotyczy.

issuedAtstringWymagane

Znacznik czasu ISO 8601 wystawienia paragonu.

receiptUrlstringOpcjonalne

URL, pod którym można pobrać paragon.

TipRecipient​

Rekord odbiorcy napiwku zwracany przez GET /merchant/v1/tipRecipients, GET /merchant/v1/tipRecipients/{id} oraz pole tipRecipient odpowiedzi PUT /merchant/v1/tipRecipients/{id}.

idstringWymagane

Identyfikator wygenerowany przez OpenApp. Aplikacja OpenApp używa tej wartości podczas potwierdzenia. POS powinien adresować rekord przez externalTipRecipientId.

merchantIdstringWymagane

Identyfikator merchanta OpenApp powiązany z poświadczeniami API.

integrationProfileIdstringWymagane

Identyfikator profilu integracji OpenApp powiązany z poświadczeniami API.

externalTipRecipientIdstringWymagane

Stabilny identyfikator po stronie POS podawany jako parametr ścieżki {id}. Jest to ta sama wartość co tipRecipientId w komunikatach płatności i kodach QR paragonu.

displayNamestringWymagane

Czytelna dla człowieka nazwa odbiorcy napiwku wyświetlana personelowi.

linkStatusstringWymagane

Aktualny stan linkowania. Zobacz Link status.

phoneNumberstringOpcjonalne

Znormalizowany numer telefonu zgłoszony do linkowania. Obecny, gdy linkStatus to PENDING, i usuwany po potwierdzeniu.

expiresAtstringOpcjonalne

Termin potwierdzenia w formacie ISO 8601. Obecny, gdy linkStatus to PENDING, i usuwany po potwierdzeniu. OpenApp odrzuca potwierdzenie po tym czasie, ale asynchroniczne usunięcie rekordu może nastąpić później.

linkedAtstringOpcjonalne

Znacznik czasu ISO 8601, w którym pracownik potwierdził link. Obecny, gdy linkStatus to ACTIVE.

Wiadomości linkowania odbiorcy napiwku​

PutTipRecipientRequest​

Treść żądania dla PUT /merchant/v1/tipRecipients/{id}. Parametr ścieżki {id} staje się externalTipRecipientId rekordu.

phoneNumberstringWymagane

Numer telefonu, który pracownik chce powiązać, w formacie E.164 (na przykład +48123456789). Pracownik może już mieć konto OpenApp albo założyć je później.

displayNamestringWymagane

Czytelna dla człowieka nazwa odbiorcy napiwku. Tworzy albo aktualizuje nazwę wyświetlaną rekordu.

LinkTipRecipientResponse​

Zwracane przez PUT /merchant/v1/tipRecipients/{id} po utworzeniu albo aktualizacji rekordu przez OpenApp.

tipRecipientTipRecipientWymagane

Wynikowy rekord TipRecipient. Jego linkStatus może być PENDING albo ACTIVE, w zależności od poprzedniego stanu rekordu i przesłanego numeru telefonu.

Enumy​

Table status​

Używane przez tableSessionContext.status i tableOrderSnapshot.status.

WartośćZnaczenie
OPENStolik jest otwarty i przyjmuje zmiany.
CLOSINGStolik jest zamykany; mutacje mogą zostać odrzucone.
CLOSEDStolik jest zamknięty.
CANCELLEDStolik został anulowany.

Mutation rejection reasons​

Używane przez OrderSubmissionResult.rejectedItems[].reasonCode.

PowódZnaczenie
OUT_OF_STOCKPozycja nie jest już dostępna.
INSUFFICIENT_STOCKŻądana ilość jest niedostępna.
DELISTEDPozycja już nie istnieje albo nie może być sprzedawana.
ORDER_CLOSEDStolik albo rachunek jest zamknięty lub zamykany.
PRICE_CHANGEDOpenApp musi odświeżyć cenę albo snapshot listingu.

Change types​

Używane przez TableOrderSnapshotChanged.changeType.

WartośćPrzypadek użycia
POS_LINE_ADDEDKelner dodaje napoje albo jedzenie bezpośrednio w POS.
LINE_CANCELLEDKuchnia albo POS anuluje linię, na przykład z powodu braku towaru.
LINE_DELIVEREDKelner oznacza napoje albo jedzenie jako wydane.
LINE_UPDATEDKelner usuwa albo rabatuje linię po reklamacji.
ORDER_CLOSEDPOS zamyka stolik albo otwarte zamówienie.

Bill preparation rejection reasons​

Używane przez BillPreparationResult.reasonCode.

PowódZnaczenie
NO_OPEN_BILLBrak otwartego albo możliwego do opłacenia rachunku dla zeskanowanego stanowiska. W przypadku stanowisk kioskowych OpenApp może w odpowiedzi zaoferować ścieżkę samoobsługowego zamówienia (K2).
ORDER_CHANGEDRewizja POS się zmieniła; OpenApp musi odświeżyć i potwierdzić z klientem.
ORDER_CLOSEDRachunek albo zamówienie jest już zamknięte.
PAYMENT_NOT_ALLOWEDPOS nie może przyjąć płatności OpenApp dla tego stolika albo zamówienia.
FISCAL_ERRORFiskalizacja albo przygotowanie paragonu nie powiodło się.
POS_OFFLINE_OR_BUSYTymczasowa awaria POS.

Activation failure reasons​

Używane przez PosActivationResponse.failureReason.

PowódZnaczenie
INVALID_OR_EXPIRED_PINPIN nie istnieje, wygasł, został już zużyty albo nie pasuje do przesłanego merchantTaxId.
ACTIVATION_NOT_ALLOWEDMerchant, profil integracji, lokalizacja albo funkcja POS nie jest w stanie pozwalającym na aktywację.

Order types​

Używane przez PosOrderTypeAvailabilityChanged.changes[].orderType.

WartośćZnaczenie
STATIONKontekst zamówienia na stanowisku (stolik albo kiosk).
PICKUPKontekst odbioru osobistego.
DELIVERYKontekst dostawy.

Order type availability states​

Używane przez PosOrderTypeAvailabilityChanged.changes[].state.

WartośćZnaczenie
ACCEPTINGOpenApp może rozpoczynać nowe zamówienia tego typu.
PAUSEDOpenApp nie może rozpoczynać nowych zamówień tego typu.

Używane przez TipRecipient.linkStatus.

WartośćZnaczenie
PENDINGOpenApp zaakceptowało zgłoszenie, ale pracownik go nie potwierdził. Rekord ma termin potwierdzenia w expiresAt.
ACTIVEPracownik potwierdził link i spełnił wymóg KYC OpenApp. Napiwki przypisane do externalTipRecipientId trafiają do jego portfela OpenApp.