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 w celu aktywacji względem OpenApp.

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.

successbooleanWymagane

true.

merchantIdstringWymagane

Identyfikator merchanta ustalony z merchantTaxId.

integrationProfileIdstringWymagane

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

locationIdstringWymagane

Identyfikator fizycznej lokalizacji.

posIdstringWymagane

Identyfikator POS nadany przez OpenApp.

apiConfigurationobjectWymagane

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

queueConfigurationobjectOpcjonalne

Obecne tylko wtedy, gdy skonfigurowano dostarczanie przez kolejkę. Zawiera URL kolejki, region i poświadczenia AWS ograniczone do kolejki funkcji 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 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 TABLE, 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 stolik albo zamówienie. Zobacz orderContext.

checkpointstringWymagane

Najnowszy checkpoint stanu po stronie POS, który posiada OpenApp. Dla kontekstów stolika jest to updatedAt z najnowszego tableOrderSnapshot. POS używa go, aby zdecydować, czy zwrócić ORDER_CHANGED, ponieważ jego stan poszedł dalej. Znacznik czasu ISO 8601.

billingDetailsobjectOpcjonalne

Dane faktury, jeśli klient poprosił o fakturę. Zobacz billingDetails.

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.

posBillIdstringWymagane

Identyfikator przygotowanego rachunku nadany przez POS.

billobjectWymagane

Zobacz bill.

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.

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.

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

TABLE. Kontekst zamówienia przy stoliku.

tableIdstringWymagane

Identyfikator stolika POS.

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.

linesarrayWymagane

Linie rachunku zamrożone przez POS. TBD

totalsobjectWymagane

Sumy rachunku. TBD

billingDetailsobjectOpcjonalne

Zobacz billingDetails.

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.

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
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
TABLEKontekst zamówienia przy stoliku.
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.