Rezerwacje

bookings.create()

bookings.create(
  input: BookingCreateInput,
  options?: RequiplyRequestOptions,
): Promise<BookingCreateResponse>

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.

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

Status początkowy rezerwacji pochodzi z ustawień tworzenia rezerwacji 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, czyli jednorazowy rabat lub dopłatę do tej rezerwacji:

"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 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(), więc najpierw możesz pokazać cenę po korekcie.

Zestawy

Od wersji 0.2.1 bundles: [{ bundleId, quantity }] rezerwuje całe komplety zestawu z identyfikatorami z bundles.list(). 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(), 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, 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ż.

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.

if (result.success) {
  console.log('Booking', result.reservationOrgId, result.isRequest);
  if (result.paymentUrl) redirectTo(result.paymentUrl);
} else {
  console.log(result.message, result.reason);
}

Oba kształty zawierają totalCost i currency. Nieprawidłowe dane wejściowe, takie jak brakujące pole lub nieznana pozycja, nadal zgłaszają RequiplyError.

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

{
  "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()

bookings.list(
  params?: BookingListParams,
  options?: RequiplyRequestOptions,
): Promise<BookingListResponse>

To operacja serwerowa z kluczem tajnym. Rezerwacje są zwracane od najnowszej według czasu utworzenia. Filtry opcjonalne:

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()

bookings.get(
  id: number,
  params?: { idKind?: 'internal' | 'org' },
  options?: RequiplyRequestOptions,
): Promise<BookingDetailResponse>

Użyj idKind: 'org', gdy id to numer rezerwacji widoczny w organizacji. W przeciwnym razie pomiń ten parametr albo użyj internal.

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ż. 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()

bookings.addNote(
  id: number,
  content: string,
  options?: RequiplyRequestOptions,
): Promise<BookingNoteResponse>

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.