Dla integratorów

Dokumentacja integracji

Jak połączyć kasę, agregator dostaw albo własny system z Rostmenu. Trzy punkty styku: przyjmowanie zamówień, wysyłka zamówień do Twojego systemu i pobieranie aktualnego menu.

Ostatnia aktualizacja: lipiec 2026

1. Zanim zaczniesz

Rostmenu udostępnia trzy punkty integracji: przyjmowanie zamówień z systemów zewnętrznych, wysyłkę zamówień do kasy lub innego systemu lokalu oraz pobieranie aktualnego menu. To wystarcza, żeby podłączyć kasę fiskalną, agregator dostaw, drukarkę kuchenną albo własny system restauracji.

adres bazowy: https://rostmenu.com;
wszystkie dane w formacie JSON, kodowanie UTF-8;
komunikacja wyłącznie po HTTPS;
integracja działa na poziomie jednego lokalu - każdy lokal ma własny token.

2. Token i autoryzacja

Token generuje właściciel lokalu w panelu: Integracje → Token dla systemów zewnętrznych. Ten sam token autoryzuje przyjmowanie zamówień i pobieranie menu.

X-Inbound-Token: <token lokalu>

Alternatywnie token można przekazać w parametrze zapytania ?token= - wygodne przy testach i w narzędziach typu Zapier czy Make, które nie pozwalają ustawić nagłówka. W środowisku produkcyjnym zalecamy nagłówek: parametry zapytania trafiają do logów serwerów pośredniczących.

Token jest tajny i daje dostęp do zamówień oraz menu lokalu. Jeśli wyciekł, właściciel generuje nowy w panelu - stary przestaje działać natychmiast.

3. Przyjmowanie zamówień (POST)

Zamówienie z systemu zewnętrznego trafia na wspólną listę zamówień lokalu z oznaczeniem źródła. Menu nie jest dopasowywane - skład przychodzi gotowy i zapisujemy go jako zdjęcie stanu.

POST /api/integrations/inbound
X-Inbound-Token: <token>
X-Idempotence-Key: <unikalny klucz próby>
Content-Type: application/json

Pole	Typ	Opis
items *	array	Pozycje zamówienia. Maksymalnie 100.
items[].name *	string	Nazwa pozycji widoczna dla obsługi. Do 120 znaków.
items[].qty	number	Ilość, 1-999. Domyślnie 1.
items[].unitPrice	number	Cena za sztukę w walucie lokalu.
items[].optionNames	string[]	Dodatki i modyfikatory, do 10 pozycji.
items[].note	string	Uwaga do pozycji, np. bez cebuli.
total	number	Kwota zamówienia. Gdy brak - liczymy z pozycji.
orderType	string	dinein, takeaway lub delivery. Domyślnie takeaway.
source	string	Nazwa źródła, np. wolt, glovo, kasa. Widoczna przy zamówieniu.
customerName	string	Imię gościa.
customerPhone	string	Telefon gościa.
address	string	Adres dostawy (dla orderType = delivery).
deliveryFee	number	Koszt dostawy.
comment	string	Uwaga do całego zamówienia.
paid	boolean	true, jeśli zamówienie zostało już opłacone po stronie platformy.

Przykład

curl -X POST https://rostmenu.com/api/integrations/inbound \
  -H "X-Inbound-Token: TWOJ_TOKEN" \
  -H "X-Idempotence-Key: wolt-8842-1" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "wolt",
    "orderType": "delivery",
    "customerName": "Anna",
    "customerPhone": "+48600100200",
    "address": "ul. Kwiatowa 5/2, Warszawa",
    "deliveryFee": 9.90,
    "paid": true,
    "items": [
      { "name": "Pizza Margherita", "qty": 2, "unitPrice": 38.00 },
      { "name": "Tiramisu", "qty": 1, "unitPrice": 22.00, "note": "bez kakao" }
    ]
  }'

Odpowiedź

{ "ok": true, "orderId": 1841 }

4. Powtórzenia i klucz idempotencji

Agregatory i kasy powtarzają żądanie, gdy nie doczekają się odpowiedzi w zadanym czasie. Bez zabezpieczenia każdy taki retry tworzy drugie zamówienie na kuchni.

Dlatego przy każdej próbie wyślij nagłówek X-Idempotence-Key z wartością unikalną dla zamówienia (np. własny numer zamówienia z Twojego systemu). Powtórzenie z tym samym kluczem w ciągu 10 minut nie utworzy nowego zamówienia - odpowiemy tym samym orderId i dodamy pole duplicate: true.

{ "ok": true, "orderId": 1841, "duplicate": true }

Klucz może zawierać litery, cyfry, myślnik i podkreślenie, do 64 znaków. Bez tego nagłówka każde żądanie traktujemy jako nowe zamówienie.

5. Wysyłka zamówień do Twojego systemu (webhook)

Właściciel podaje w panelu adres w polu Integracje → Adres webhooka. Pod ten adres wysyłamy metodą POST każde aktualne zamówienie - z sali, z dostawy i opłacone kartą.

format treści: to samo zamówienie, które widzi panel (numer, stolik, pozycje, kwoty, status);
wysyłka jest jednokierunkowa i nie blokuje obsługi gościa;
limit czasu odpowiedzi: 5 sekund. Odpowiadaj od razu, przetwarzaj po swojej stronie;
adres musi być publiczny i po HTTPS. Adresy lokalne i sieci prywatnych są odrzucane;
nie ponawiamy wysyłki - zamówienie pozostaje dostępne w panelu i przez API.

Jeśli Twoja kasa jest na liście obsługiwanych w panelu (m.in. Poster, Dotykačka, Syrve, GoPOS, POSbistro, Gastro POS), wystarczy wybrać ją z listy i podać identyfikator lokalu - własny webhook nie jest wtedy potrzebny.

6. Pobieranie menu (GET)

Zwraca aktualne kategorie i dania z cenami. Przydaje się, gdy Twój system ma pokazywać albo weryfikować kartę, zamiast trzymać jej własną kopię, która po miesiącu rozjeżdża się z prawdą.

GET /api/integrations/menu?lang=pl
X-Inbound-Token: <token>

Parametr lang jest opcjonalny - bez niego zwracamy podstawowy język menu lokalu. Nazwy i opisy przychodzą jako gotowe teksty w wybranym języku.

{
  "restaurant": { "slug": "bistro-aurora", "name": "Bistro Aurora", "currency": "PLN", "vatRate": 8 },
  "categories": [ { "id": 12, "name": "Dania główne", "sort": 3 } ],
  "dishes": [
    {
      "id": 340,
      "categoryId": 12,
      "name": "Stek ribeye",
      "description": "Sezonowana wołowina 300 g, masło ziołowe",
      "price": 89,
      "available": true,
      "stockLeft": null,
      "vatRate": null,
      "allergens": ["milk"],
      "modifiers": [
        { "id": "size", "name": "Stopień wysmażenia", "required": true, "multi": false,
          "options": [ { "id": "rare", "name": "Rare", "price": 0 } ] }
      ]
    }
  ]
}

Pole available: false oznacza pozycję zdjętą z karty (stop-lista), a vatRate: null - że obowiązuje stawka lokalu z sekcji restaurant. Endpoint jest wyłącznie do odczytu: nie zmienia niczego w menu.

7. Kody odpowiedzi i błędy

Błędy zwracamy w jednym formacie:

{ "error": "unauthorized", "message": "Nieprawidłowy lub brakujący token integracji" }

Kod	error	Znaczenie
200	-	Odczyt zakończony powodzeniem
201	-	Zamówienie utworzone
400	empty	Brak pozycji w zamówieniu
401	unauthorized	Zły lub brakujący token
429	too_many	Przekroczony limit zapytań

Limity: 300 zamówień / 5 minut oraz 120 pobrań menu / 5 minut na adres IP. Po przekroczeniu odczekaj i ponów - najlepiej z tym samym kluczem idempotencji.

8. Lista kontrolna wdrożenia

Właściciel lokalu generuje token w panelu i przekazuje go Tobie bezpiecznym kanałem.
Wyślij jedno zamówienie testowe i sprawdź, czy pojawia się w panelu z właściwym źródłem.
Powtórz to samo żądanie z tym samym kluczem idempotencji - powinieneś dostać ten sam numer zamówienia.
Jeśli odbierasz zamówienia u siebie, podaj adres webhooka i sprawdź, czy odpowiadasz poniżej 5 sekund.
Jeśli korzystasz z menu, pobierz je i sprawdź obsługę pola available oraz modyfikatorów.
Ustal, co robisz przy 429 i przy braku odpowiedzi - ponowienie z tym samym kluczem jest bezpieczne.

9. Pytania i zgłoszenia

Pytania techniczne, prośby o nowe pola albo zgłoszenia błędów: [email protected]. W zgłoszeniu podaj nazwę lokalu, przybliżoną godzinę zdarzenia i treść żądania - to zwykle wystarcza, żeby odtworzyć sytuację.

Rozwijamy integracje na podstawie realnych zgłoszeń. Jeśli potrzebujesz czegoś, czego tu nie ma - napisz, co dokładnie chcesz osiągnąć.