--- title: "Rezerwacje" description: "Twórz zapytania o rezerwację i zarządzaj rezerwacjami za pomocą SDK Requiply." canonical_url: "https://requiply.com/docs/pl/developers/typescript-sdk/bookings" --- # Rezerwacje > Twórz zapytania o rezerwację i zarządzaj rezerwacjami za pomocą SDK Requiply. ## `bookings.create()` ```ts bookings.create( input: BookingCreateInput, options?: RequiplyRequestOptions, ): Promise ``` Wymagane: `startDate`, `endDate`, `items` (do 100) i `deliveryType` (`pickup` lub `delivery`). Zwykła rezerwacja wymaga też `paymentType`, a zapytanie o rezerwację (`asRequest: true`) nie. Opcjonalne: `bundles`, `services`, `clientId` lub dane klienta w `client`, `allowOutsideWorkingHours`, `adjustment` i `saleLines`. `paymentType` przyjmuje `payOnPickup`, `stripe`, `wayforpay`, `monobank` lub `liqpay`. Metoda online wymaga aktywnej integracji z danym operatorem. ```ts const result = await requiply.bookings.create({ startDate: '2026-07-01T10:00:00', endDate: '2026-07-03T18:00:00', items: [{ groupId: cameraKitId, quantity: 1 }], deliveryType: 'pickup', asRequest: true, client: { name: 'Alex', email: 'customer@example.com' }, }); ``` `client` wymaga `email` lub `phone` i może zawierać też `name` i `lastName`. Jest dopasowywany do istniejącego klienta po adresie e-mail, potem po telefonie, a gdy żaden nie pasuje, zostaje utworzony. Integracja serwerowa, która już zna klienta, może zamiast tego przekazać `clientId`. Zapytanie o rezerwację nie blokuje sprzętu i nie tworzy płatności, dopóki pracownicy go nie zatwierdzą. Klucze publiczne mogą używać tej metody tylko do zapytań o rezerwację z `asRequest: true`. Zwykłe rezerwacje twórz kluczem tajnym na zaufanym serwerze. Status początkowy rezerwacji pochodzi z [ustawień tworzenia rezerwacji](https://requiply.com/docs/pl/guides/settings/bookings/booking-creation#wyb%C3%B3r-status%C3%B3w-pocz%C4%85tkowych) organizacji: **Status zapytań o rezerwację**, gdy `asRequest` ma wartość `true`, a w przeciwnym razie **Domyślny status nowych rezerwacji**. Statusy należą do każdej organizacji i można zmieniać ich nazwy, więc nie wpisuj na stałe w integracji nazwy statusu, takiej jak `Request` czy `New`. Data z godziną bez przesunięcia, na przykład `2026-07-01T10:00:00`, jest odczytywana jako czas lokalny w strefie czasowej organizacji, z uwzględnieniem czasu letniego. Wartość z `Z` lub przesunięciem jest używana bez zmian. Data bez godziny, na przykład `2026-07-01`, jest odczytywana jako północ i zwykle nie przechodzi sprawdzenia godzin pracy, więc zawsze podawaj godzinę. `startDate` i `endDate` muszą przypadać w dzień pracy, w godzinach pracy organizacji, w jej strefie czasowej. W przeciwnym razie odpowiedź ma `success: false`, `reason: "working_hours"` i komunikat z opisem dozwolonego przedziału. Klucz tajny może przekazać `allowOutsideWorkingHours: true`, aby pominąć to sprawdzenie przy wydaniu lub zwrocie, który firma zgodziła się obsłużyć poza godzinami pracy. Klucze publiczne nie mogą używać tej flagi i dostają `403`. ### Korekta kosztu rezerwacji Punkt końcowy REST `POST /api/public/v1/bookings/create` przyjmuje też jedną [korektę kosztu rezerwacji](https://requiply.com/docs/pl/guides/bookings/changing/cost-adjustment), czyli jednorazowy rabat lub dopłatę do tej rezerwacji: ```json "adjustment": { "type": "percent", "value": -10, "reason": "Returning client" } ``` `type` to `units` (naliczane dni lub miesiące), `percent` (od −100 do 100) lub `amount` (waluta organizacji). Wartość ma znak: ujemna oznacza rabat, dodatnia dopłatę. Może ją wysłać tylko **klucz tajny**, grupa uprawnień klucza musi mieć **Zezwalaj na korekty kosztu i kaucji**, a dany typ musi być włączony w [Funkcje](https://requiply.com/docs/pl/guides/settings/organization/features#w%C5%82%C4%85cz-korekty-kosztu-i-kaucji) organizacji. W przeciwnym razie odpowiedzią jest `403` (na przykład *adjustment requires a secret key* lub *Booking adjustments are not enabled for this organization*) albo `400` dla wartości zero bez powodu. To samo pole działa w [`pricing.quote()`](https://requiply.com/docs/pl/developers/typescript-sdk/availability-and-pricing#pricingquote), więc najpierw możesz pokazać cenę po korekcie. ### Zestawy Od wersji 0.2.1 `bundles: [{ bundleId, quantity }]` rezerwuje całe komplety [zestawu](https://requiply.com/docs/pl/guides/inventory/bundles) z identyfikatorami z [`bundles.list()`](https://requiply.com/docs/pl/developers/typescript-sdk/inventory-and-categories#bundleslist). `items` może być wtedy puste. Pozycje zestawu są zapisywane w rezerwacji jako zwykłe pozycje z rabatem zestawu, a rabat klienta jest naliczany dodatkowo. Wysłanie zestawów, gdy organizacja ma wyłączoną funkcję Zestawy, zwraca `403`. Najpierw wyceń te same `bundles` za pomocą [`pricing.quote()`](https://requiply.com/docs/pl/developers/typescript-sdk/availability-and-pricing#pricingquote), aby pokazać `bundleDiscountAmount`. ### Towary na sprzedaż Przy włączonej funkcji Sprzedaż `saleLines: [{ saleItemId, quantity }]` sprzedaje towary razem z rezerwacją po cenie katalogowej. Klucz publiczny może je dodać do zapytania o rezerwację tylko wtedy, gdy organizacja [sprzedaje klientom](https://requiply.com/docs/pl/developers/typescript-sdk/sales#z-kluczem-publicznym), i nigdy ponad stan magazynowy. Suma za towary jest dodawana do `totalCost`, stan magazynowy spada po utworzeniu rezerwacji i wraca, jeśli rezerwacja zostanie anulowana. Zobacz [Sprzedaż i towary na sprzedaż](https://requiply.com/docs/pl/developers/typescript-sdk/sales#towary-w-rezerwacji). Zapytania o rezerwację z kluczem publicznym nie mogą zawierać identyfikatorów pozycji z podnajmu od dostawców. Rezerwacje tworzone kluczem tajnym mogą je zawierać, gdy organizacja włączyła podnajem. Każda wybrana pozycja tworzy zapisaną na stałe pozycję zamówienia u dostawcy zamiast przypisywać egzemplarz z własnego sprzętu. ### Obsługa odpowiedzi `bookings.create()` zwraca jeden z dwóch kształtów, rozróżnianych przez `success`. Rezerwacja, której organizacja nie może przyjąć, **nie** zgłasza wyjątku: kończy się wynikiem `success: false`. TypeScript pozwala odczytać `reservationId` dopiero po sprawdzeniu `success`. ```ts if (result.success) { console.log('Booking', result.reservationOrgId, result.isRequest); if (result.paymentUrl) redirectTo(result.paymentUrl); } else { console.log(result.message, result.reason); } ```
success: true ( BookingCreated ) success: false ( BookingRefused )
reservationId : wewnętrzny identyfikator dla bookings.get() . message : powód odrzucenia rezerwacji, na przykład brak dostępności pozycji w tych datach.
reservationOrgId : numer rezerwacji, który pracownicy widzą w aplikacji. reason : working_hours lub minimum_duration , gdy naruszono regułę rezerwacji. Nie występuje przy innych odmowach, na przykład z powodu dostępności.
isRequest : true dla zapytania o rezerwację. minimumDuration : szczegóły odmowy minimum_duration , zobacz niżej.
paymentUrl lub paymentRedirect : dokąd przekierować klienta na płatność online. Przekierowanie post_form zawiera pola formularza fields .
Oba kształty zawierają `totalCost` i `currency`. Nieprawidłowe dane wejściowe, takie jak brakujące pole lub nieznana pozycja, nadal zgłaszają [`RequiplyError`](https://requiply.com/docs/pl/developers/typescript-sdk/error-handling). ### Minimalny czas rezerwacji `endDate` musi być późniejsze niż `startDate` (w przeciwnym razie `400` *endDate must be after startDate*), a rezerwacja musi trwać co najmniej tyle, ile wynosi **Minimalny czas rezerwacji** z ustawień [Czas trwania rezerwacji](https://requiply.com/docs/pl/guides/settings/bookings/booking-duration) organizacji (24 godziny, jeśli tego nie zmieniono). Krótsza rezerwacja jest odrzucana z `success: false`, `reason: "minimum_duration"` i obiektem `minimumDuration`, na podstawie którego możesz zaproponować prawidłowy zwrot: ```json { "success": false, "reason": "minimum_duration", "message": "...", "minimumDuration": { "minimumDurationMinutes": 1440, "requestedDurationMinutes": 240, "earliestReturn": "2026-10-07T10:00", "timeZone": "Europe/Kyiv" } } ``` `earliestReturn` to najwcześniejszy zwrot akceptowany dla tego wydania, jako czas lokalny (`YYYY-MM-DDTHH:mm`) w strefie `timeZone`. Czas trwania jest mierzony według lokalnego zegara organizacji, więc zmiana czasu na letni lub zimowy nie skraca ani nie wydłuża rezerwacji. ## `bookings.list()` ```ts bookings.list( params?: BookingListParams, options?: RequiplyRequestOptions, ): Promise ``` To operacja serwerowa z kluczem tajnym. Rezerwacje są zwracane od najnowszej według czasu utworzenia. Filtry opcjonalne:
Parametr Działanie
dateFrom , dateTo Rezerwacje, których wydanie ( startDate ) przypada w tym zakresie. Sama data oznacza północ, więc dateTo: '2026-07-31' pomija wydania później 31 lipca. Przekaż '2026-07-31T23:59:59' albo następny dzień.
createdFrom , createdTo Rezerwacje utworzone w tym zakresie. Przydaje się do synchronizacji nowych rezerwacji od ostatniego uruchomienia.
status Nazwa jednego statusu albo kilka nazw rozdzielonych przecinkami, bez rozróżniania wielkości liter. Statusy należą do każdej organizacji, więc odczytaj nazwy we własnej aplikacji. Nieznana nazwa zwraca pustą listę.
clientId Rezerwacje jednego klienta.
limit , cursor Rozmiar strony (od 1 do 200, domyślnie 50) i nextCursor poprzedniej strony.
```ts const page = await requiply.bookings.list({ dateFrom: '2026-07-01', dateTo: '2026-07-31', limit: 25, }); ``` Odpowiedź zawiera `bookings`, `currency` i `nextCursor: string | null`. Pola statusu, klienta, kosztu całkowitego i numeru rezerwacji w organizacji w elementach listy mogą mieć wartość `null`. ## `bookings.get()` ```ts bookings.get( id: number, params?: { idKind?: 'internal' | 'org' }, options?: RequiplyRequestOptions, ): Promise ``` Użyj `idKind: 'org'`, gdy `id` to numer rezerwacji widoczny w organizacji. W przeciwnym razie pomiń ten parametr albo użyj `internal`. ```ts const { booking } = await requiply.bookings.get(1042, { idKind: 'org' }); ``` Rezerwacja zawiera pozycje, usługi i płatności. Kilka pól statusu, klienta, ceny, operatora i adresu URL płatności może mieć wartość `null`. `items` wymienia zarezerwowaną ilość każdej pozycji, nawet gdy egzemplarze są przypisywane dopiero przy wydaniu. `saleItems` wymienia towary sprzedane razem z rezerwacją, a `saleId` wskazuje ich [sprzedaż](https://requiply.com/docs/pl/developers/typescript-sdk/sales#salesget). Oba są puste lub mają wartość `null`, gdy nic nie sprzedano albo funkcja Sprzedaż jest wyłączona. Suma za towary jest zawsze wliczona w `totalCost`. ## `bookings.addNote()` ```ts bookings.addNote( id: number, content: string, options?: RequiplyRequestOptions, ): Promise ``` ```ts const note = await requiply.bookings.addNote(42, 'Customer confirmed pickup time.'); ``` `content` może mieć do 4000 znaków. Notatka jest wewnętrzna: pracownicy widzą ją w rezerwacji, a klient nigdy. Odpowiedź zawiera `noteId`, `reservationId` oraz `createdAt`, które może mieć wartość `null`. To operacja serwerowa z kluczem tajnym. ## Sitemap See the full [sitemap](https://requiply.com/docs/sitemap.md) for all pages.