Для розробників

Довідник REST API

Кожен ендпоінт публічного REST API Requiply v1: HTTP-метод, типи ключів, які він приймає, метод SDK, що його обгортає. А також правила запитів, пагінація, дати та помилки.

Публічний API розташований за адресою:

https://api.requiply.com/api/public/v1

Кожен запит автентифікується через Authorization: Bearer <api-key>; див. Автентифікація та API ключі. Тіла запитів і відповідей передаються в JSON. TypeScript SDK обгортає кожен ендпоінт нижче, а його посібники з ресурсів докладно описують поля.

Документ OpenAPI поки не опубліковано. Найточніше кожен запит і відповідь описують типи TypeScript у SDK.

Ендпоінти

Ендпоінти Публічний приймають обидва типи ключів. Ендпоінти Секретний відхиляють публічний ключ із 403.

Організація та каталог

Метод і шлях	Ключі	Метод SDK
`GET /org/info`	Публічний	`org.info()`
`GET /org/summary`	Секретний	`org.summary()`
`GET /categories/list`	Публічний	`categories.list()`
`GET /services/list`	Публічний	`services.list()`
`GET /inventory/list`	Публічний	`inventory.list()`
`GET /inventory/groups/{id}`	Публічний	`inventory.getGroup()`
`GET /inventory/status`	Секретний	`inventory.status()`
`GET /bundles/list`	Публічний	`bundles.list()`
`GET /bundles/{id}`	Публічний	`bundles.get()`

Комплекти є фіксованими наборами товарів з однією знижкою. Обидва ендпоінти комплектів приймають необовʼязкові параметри запиту startDate і endDate. Якщо передати обидва, кожен комплект повідомляє availableQuantity, тобто кількість цілих наборів, вільних у цей період. Вони перелічують лише повні активні комплекти. Секретний ключ бачить комплекти щоразу, коли ввімкнено функцію «Комплекти». Публічний ключ бачить їх, лише коли також увімкнено рекомендації Зовнішні. Інакше список порожній, а bundles/{id} повертає 404. GET /inventory/groups/{id} також повертає bundles, що містять цю групу.

Доступність, ціни та бронювання

Метод і шлях	Ключі	Метод SDK
`POST /availability/calendar`	Публічний	`availability.calendar()`
`POST /availability/items`	Публічний	`availability.items()`
`POST /pricing/quote`	Публічний	`pricing.quote()`
`POST /bookings/create`	Публічний, лише запити на бронювання	`bookings.create()`
`GET /bookings/list`	Секретний	`bookings.list()`
`GET /bookings/{id}`	Секретний	`bookings.get()`
`POST /bookings/{id}/notes`	Секретний	`bookings.addNote()`

Публічний ключ має надсилати "asRequest": true у POST /bookings/create. Будь-що інше отримує 403 з data.reason: "request_only".

POST /pricing/quote і POST /bookings/create приймають bundles: [{ bundleId, quantity }] поруч з items; тоді items може бути порожнім. Розрахунки ціни повертають bundleDiscountAmount (уже враховано в total) і lineBundles, по одному запису на кожен комплект із ціною за період. Якщо надіслати комплекти, коли функцію «Комплекти» вимкнено, відповідь буде 403.

Клієнти

Метод і шлях	Ключі	Метод SDK
`POST /clients/lookup`	Секретний	`clients.lookup()`
`POST /clients/create`	Секретний	`clients.create()`

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

Метод і шлях	Ключі	Метод SDK
`GET /sale-items/list`	Секретний; публічний, поки організація продає клієнтам	`saleItems.list()`
`GET /sale-items/{id}`	Секретний; публічний, поки організація продає клієнтам	`saleItems.get()`
`GET /sales/list`	Секретний	`sales.list()`
`GET /sales/{id}`	Секретний	`sales.get()`
`POST /sales/create`	Секретний	`sales.create()`

Ці ендпоінти повертають 403 з data.reason: "feature_disabled", поки Увімкнути продажі вимкнено у Функції або організація не на тарифі Advanced. Що бачить публічний ключ і коли він натомість отримує selling_disabled, описано в Продажі та товари на продаж.

Звіти

Усі звіти потребують секретного ключа і приймають параметри в рядку запиту.

Метод і шлях	Метод SDK
`GET /reports/revenue`	`reports.revenue()`
`GET /reports/bookings-summary`	`reports.bookingsSummary()`
`GET /reports/utilization`	`reports.utilization()`
`GET /reports/top-items`	`reports.topItems()`
`GET /reports/top-clients`	`reports.topClients()`
`GET /reports/outstanding`	`reports.outstanding()`
`GET /reports/overdue`	`reports.overdue()`
`GET /reports/pipeline`	`reports.pipeline()`

Правила

Тема	Правило
Параметри	Ендпоінти `GET` приймають параметри в рядку запиту. Ендпоінти `POST` приймають тіло JSON.
Пагінація	Ендпоінти списків повертають `nextCursor`. Передайте його назад як `cursor`, щоб отримати наступну сторінку; `null` означає, що сторінок більше немає. `limit` становить від 1 до 100 (за замовчуванням 25) для списків каталогу, доступності та продажів, від 1 до 200 (за замовчуванням 50) для `bookings/list` і від 1 до 500 (за замовчуванням 100) для `inventory/status`.
Дати й час	ISO 8601. У розрахунках ціни, створенні бронювання та `availability/items` дата й час без зсуву (`2026-07-01T10:00:00`) читаються в часовому поясі організації з урахуванням переходу на літній час. Значення із `Z` або зсувом використовується як є. Дата без часу означає північ.
Ідентифікатори	Товари, категорії, послуги, товари на продаж і продажі використовують UUID. Бронювання й клієнти використовують числа. Бронювання й продажі також мають номер, який співробітники бачать у застосунку: передавайте його з `?idKind=org`.
Гроші	Суми вказуються в основній одиниці валюти організації (наприклад, `1250.5`) поруч із кодом `currency`.
Суборенда	Товари від постачальників ніколи не повертаються публічному ключу й не приймаються від нього. Секретний ключ бачить їх, коли ввімкнено суборенду.

Помилки

Невдалий запит отримує HTTP-статус помилки та тіло JSON:

{
  "statusCode": 409,
  "message": "Only 2 × Memory card 128 GB left",
  "data": { "reason": "out_of_stock", "saleItemId": "3f6c…", "availableQuantity": 2 }
}

message призначене для людей. Коли API надає машиночитну причину, вона міститься в data.reason, іноді з додатковими полями в data. Будуйте логіку на data.reason, а не на тексті повідомлення. Причини перелічено в Обробка помилок.

Статус	Типова причина
`400`	Відсутнє чи неправильно сформоване поле, наприклад недійсна дата чи порожній список `items`.
`401`	Заголовок `Authorization` відсутній, або ключ невідомий чи відкликаний.
`403`	Тип ключа не може використовувати ендпоінт, або функцію чи дозвіл вимкнено.
`404`	Бронювання, товару, клієнта чи продажу не існує в цій організації.
`409`	Запит конфліктує з поточним станом, наприклад товар архівовано або його немає в наявності.
`429`	Ключ перевищив обмеження частоти запитів. Зачекайте стільки секунд, скільки вказано в `Retry-After`.

Бронювання, яке організація не може прийняти, наприклад тому що товари зайняті або видача припадає на неробочий час, не є помилкою: POST /bookings/create повертає 200 із success: false. Див. Бронювання.

Запис продажу через REST

POST /sales/create приймає:

{
  "lines": [{ "saleItemId": "3f6c…", "quantity": 2 }],
  "clientId": 23,
  "paymentMethod": "payOnPickup",
  "soldAt": "2026-09-29T14:00:00Z",
  "note": "Counter sale"
}

Він повертає 201 із sale, stockWarnings (товари, залишок яких опускається нижче нуля; продаж однаково записується) і payment з посиланням для онлайн-способу оплати. Правила полів описано в sales.create().

Звіти

Отримуйте звіти про дохід, бронювання, завантаженість, клієнтів, баланси, прострочення та майбутні бронювання.

Приклади

Готові для копіювання підходи SDK для вітрини оренди та серверної інтеграції: каталог на дати, форма запиту на бронювання, товари на продаж, синхронізація нових бронювань і обробка обмежень частоти запитів.