Бронювання

bookings.create()

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

Обовʼязкові: startDate, endDate, items (до 100), deliveryType (pickup або delivery). Звичайне бронювання також потребує paymentType, а запит на бронювання (asRequest: true) не потребує. Необовʼязкові: bundles, services, clientId або дані клієнта в client, allowOutsideWorkingHours, adjustment, saleLines.

paymentType приймає payOnPickup, stripe, wayforpay, monobank або liqpay. Онлайн-спосіб оплати потребує активної інтеграції з цим провайдером.

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 потребує email або phone і може додатково містити name і lastName. Його зіставляють із наявним клієнтом за email, потім за телефоном, а якщо збігу немає, створюють нового. Серверна інтеграція, яка вже знає клієнта, може натомість передати clientId. Запит на бронювання не утримує інвентар і не створює оплати, доки його не підтвердять співробітники.

Початковий статус бронювання береться з налаштувань створення бронювання організації: Статус запитів на бронювання, коли asRequest дорівнює true, інакше Типовий статус нових бронювань. Статуси належать кожній організації та можуть бути перейменовані, тож не вписуйте у свою інтеграцію жорстко назву статусу на кшталт Request чи New.

Дата й час без зсуву, як-от 2026-07-01T10:00:00, читаються як місцевий час у часовому поясі організації з урахуванням переходу на літній час. Значення із Z або зсувом використовується як є. Дата без часу, як-от 2026-07-01, читається як північ і зазвичай не проходить перевірку робочих годин, тож завжди надсилайте час.

startDate і endDate мають припадати на робочий день у межах робочих годин організації, які оцінюються в часовому поясі організації. Інакше відповідь містить success: false, reason: "working_hours", а також повідомлення з дозволеним проміжком. Секретний ключ може передати allowOutsideWorkingHours: true, щоб пропустити цю перевірку для видачі чи повернення, які бізнес погодився провести поза графіком. Публічні ключі не можуть використовувати цей прапорець і отримують 403.

Коригування вартості бронювання

REST-ендпоінт POST /api/public/v1/bookings/create також приймає одне коригування вартості бронювання, тобто разову знижку чи доплату для цього бронювання:

"adjustment": { "type": "percent", "value": -10, "reason": "Returning client" }

type може бути units (оплачувані дні чи місяці), percent (від −100 до 100) або amount (у валюті організації). Значення має знак: відʼємне означає знижку, додатне означає доплату. Надсилати його може лише секретний ключ, група дозволів ключа має мати Коригування вартості та застави, а тип має бути ввімкнено у Функції організації. Інакше відповідь буде 403 (наприклад, adjustment requires a secret key або Booking adjustments are not enabled for this organization) чи 400 для нульового значення без причини. Те саме поле працює в pricing.quote(), тож спершу можна показати скориговану ціну.

Комплекти

Починаючи з 0.2.1, bundles: [{ bundleId, quantity }] бронює цілі набори комплекту з ідентифікаторами з bundles.list(). Тоді items може бути порожнім. Товари комплекту записуються в бронювання як звичайні рядки товарів із застосованою знижкою за комплект, а знижка клієнта додається зверху. Якщо надіслати комплекти, коли в організації вимкнено функцію «Комплекти», відповідь буде 403. Спершу розрахуйте ціну з тими самими bundles через pricing.quote(), щоб показати bundleDiscountAmount.

Товари на продаж

Коли функцію «Продажі» ввімкнено, saleLines: [{ saleItemId, quantity }] продає товари разом із бронюванням за каталожною ціною. Публічний ключ може додати їх до запиту на бронювання, лише поки організація продає клієнтам, причому ніколи понад наявний залишок. Сума товарів додається до totalCost. Залишок зменшується під час створення бронювання і повертається, якщо бронювання скасують. Див. Продажі та товари на продаж.

Публічні запити на бронювання не можуть містити ідентифікаторів товарів суборенди від постачальників. Створення бронювання із секретним ключем може їх містити, коли організація ввімкнула суборенду. Кожен вибраний товар створює зафіксований рядок закупівлі замість призначення власної одиниці інвентарю.

Обробка відповіді

bookings.create() повертає одну з двох форм, які розрізняють за success. Бронювання, яке організація не може прийняти, не викидає помилку: метод повертає success: false. TypeScript дозволяє читати reservationId лише після перевірки success.

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

Обидві форми містять totalCost і currency. Неправильні вхідні дані (як-от відсутнє поле чи невідомий товар) і далі викидають RequiplyError.

Мінімальна тривалість бронювання

endDate має бути пізніше за startDate (інакше 400 endDate must be after startDate). Бронювання також має тривати щонайменше Мінімальна тривалість бронювання з налаштувань Тривалість бронювання організації (24 години, якщо не змінено). Коротше бронювання відхиляється з success: false, reason: "minimum_duration", а також обʼєктом minimumDuration, за яким можна запропонувати допустимий час повернення:

{
  "success": false,
  "reason": "minimum_duration",
  "message": "...",
  "minimumDuration": {
    "minimumDurationMinutes": 1440,
    "requestedDurationMinutes": 240,
    "earliestReturn": "2026-10-07T10:00",
    "timeZone": "Europe/Kyiv"
  }
}

earliestReturn є найранішим допустимим поверненням для цієї видачі як місцевий час (YYYY-MM-DDTHH:mm) у timeZone. Тривалість вимірюється за місцевим часом організації, тож перехід на літній час не робить бронювання коротшим чи довшим.

bookings.list()

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

Це серверна операція із секретним ключем. Бронювання йдуть від найновіших за часом створення. Необовʼязкові фільтри:

const page = await requiply.bookings.list({
  dateFrom: '2026-07-01',
  dateTo: '2026-07-31',
  limit: 25,
});

Відповідь містить bookings, currency, а також nextCursor: string | null. Поля статусу, клієнта, загальної вартості та номера бронювання в організації в елементах списку можуть бути null.

bookings.get()

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

Використовуйте idKind: 'org', коли id є номером бронювання, який бачить організація. Інакше не передавайте параметр або використовуйте internal.

const { booking } = await requiply.bookings.get(1042, { idKind: 'org' });

Бронювання містить товари, послуги та оплати. Кілька полів статусу, клієнта, ціни, провайдера та URL оплати можуть бути null. items перелічує заброньовану кількість кожного товару, навіть коли одиниці призначають лише під час видачі.

saleItems перелічує товари, продані разом із бронюванням, а saleId вказує на їхній продаж. Обидва порожні або null, коли нічого не продано чи функцію «Продажі» вимкнено. Сума товарів завжди входить у 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 має до 4000 символів. Нотатка внутрішня: співробітники бачать її в бронюванні, клієнт ніколи. Відповідь містить noteId, reservationId, а також createdAt, який може бути null. Це серверна операція із секретним ключем.