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.

merchantTaxIdstringRequired

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

pinCodestringRequired

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

posInstallationIdstringOptional

Stabilny identyfikator instalacji POS po stronie merchanta.

softwareNamestringRequired

Nazwa produktu oprogramowania POS.

softwareVersionstringRequired

Ciąg wersji oprogramowania POS.

PosActivationResponse​

Zwracane przez OpenApp w odpowiedzi na ActivatePos.

successbooleanRequired

true.

merchantIdstringRequired

Identyfikator merchanta ustalony z merchantTaxId.

integrationProfileIdstringRequired

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

locationIdstringRequired

Identyfikator fizycznej lokalizacji.

posIdstringRequired

Identyfikator POS nadany przez OpenApp.

apiConfigurationobjectRequired

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

queueConfigurationobjectOptional

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.

healthybooleanRequired

Aktualny stan zdrowia POS.

softwareNamestringRequired

Nazwa produktu oprogramowania POS.

softwareVersionstringRequired

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.

openbooleanRequired

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

reasonCodestringOptional

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

messagestringOptional

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

effectiveAtstringOptional

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 objectsRequired

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.

Show child parametersHide child parameters
orderTypeOrderTypeRequired

Typ zamówienia do zmiany. Zobacz Order types.

stateOrderTypeAvailabilityStateRequired

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

reasonCodestringOptional

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

effectiveUntilstringOptional

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 | nullRequired

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

ProductListingsSynced​

checkpointobjectRequired

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

listingsarrayRequired

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

ProductListingsUpdated​

listingsarrayRequired

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

Wiadomości zamawiania przy stoliku​

TableOrderSnapshotRequested​

tableIdstringRequired

Identyfikator stolika POS ustalony przez OpenApp z QR.

checkpointstringOptional

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.

successbooleanRequired

true.

tableSessionContextobjectRequired

Zobacz tableSessionContext.

tableOrderSnapshotobjectRequired

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ą.

orderContextobjectRequired

Zobacz orderContext.

itemsarrayRequired

Pozycje wysyłane do POS. TBD

paymentobjectOptional

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.

successbooleanRequired

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

acceptedItemsarrayRequired

Pozycje zaakceptowane przez POS. TBD

tableOrderSnapshotobjectOptional

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

receiptobjectOptional

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.

changeTypestringRequired

Zobacz Change types.

diffobjectRequired

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

reasonCodestringOptional

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​

orderContextobjectRequired

Identyfikuje stolik albo zamówienie. Zobacz orderContext.

checkpointstringRequired

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.

billingDetailsobjectOptional

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

itemsarrayOptional

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.

successbooleanRequired

true.

posBillIdstringRequired

Identyfikator przygotowanego rachunku nadany przez POS.

billobjectRequired

Zobacz bill.

BillPaymentCompleted​

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

paymentobjectRequired

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

posBillIdstringRequired

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.

posBillIdstringRequired

Identyfikator nadany przez POS i zwrócony w BillPreparationResult.

reasonCodestringRequired

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.

successbooleanRequired

true.

receiptobjectRequired

Zobacz receipt.

Modele bazowe​

orderContext​

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

typestringRequired

TABLE. Kontekst zamówienia przy stoliku.

tableIdstringRequired

Identyfikator stolika POS.

customerNotestringOptional

Notatka tekstowa widoczna dla POS.

tableSessionContext​

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

locationIdstringRequired

Fizyczna lokalizacja restauracji.

tableIdstringRequired

Identyfikator stolika POS.

tableNumberstringRequired

Numer stolika czytelny dla człowieka.

statusstringRequired

Zobacz Table status.

openedAtstringRequired

Znacznik czasu ISO 8601 otwarcia stolika.

closedAtstringOptional

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.

tableIdstringRequired

Identyfikator stolika POS.

statusstringRequired

Zobacz Table status.

linesarrayRequired

Linie zamówienia POS. TBD

totalsobjectRequired

Sumy rachunku. TBD

paymentsarrayRequired

Płatności zastosowane w POS. TBD

updatedAtstringRequired

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

taxIdstringRequired

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

companyNamestringRequired

Nazwa prawna na fakturze.

addressobjectRequired

Adres pocztowy. TBD

bill​

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

posBillIdstringRequired

Identyfikator przygotowanego rachunku nadany przez POS.

linesarrayRequired

Linie rachunku zamrożone przez POS. TBD

totalsobjectRequired

Sumy rachunku. TBD

billingDetailsobjectOptional

Zobacz billingDetails.

preparedAtstringRequired

Znacznik czasu ISO 8601 przygotowania i zamrożenia rachunku.

payment​

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

oaPaymentIdstringRequired

Identyfikator płatności OpenApp.

amountobjectRequired

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

paidAtstringRequired

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

receipt​

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

receiptNumberstringRequired

Numer paragonu nadany przez POS.

fiscalSignaturestringOptional

Podpis fiskalizacji, jeśli dotyczy.

issuedAtstringRequired

Znacznik czasu ISO 8601 wystawienia paragonu.

receiptUrlstringOptional

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.