--- title: "Продажі та товари на продаж" description: "Отримуйте список товарів на продаж і їхніх залишків, читайте й записуйте продажі та продавайте товари разом із бронюванням через SDK." canonical_url: "https://requiply.com/docs/uk/developers/typescript-sdk/sales" --- # Продажі та товари на продаж > Отримуйте список товарів на продаж і їхніх залишків, читайте й записуйте продажі та продавайте товари разом із бронюванням через SDK. Ці ресурси охоплюють модуль [Продажі](https://requiply.com/docs/uk/guides/sales): товари на кшталт карт памʼяті, батарей чи гаферного скотчу, які орендний бізнес продає з обліком залишку поруч з орендою. Організація має бути на тарифі Advanced з увімкненим **Увімкнути продажі** у [Функції](https://requiply.com/docs/uk/guides/settings/organization/features#%D1%83%D0%B2%D1%96%D0%BC%D0%BA%D0%BD%D1%83%D1%82%D0%B8-%D0%BF%D1%80%D0%BE%D0%B4%D0%B0%D0%B6%D1%96). Інакше кожен метод викидає `RequiplyError` зі `status` `403` і `reason` `feature_disabled` (`selling_disabled` для публічного ключа).
Метод Секретний ключ Публічний ключ
saleItems.list() , saleItems.get() Так Лише активні товари, поки організація продає клієнтам
saleLines у pricing.quote() і bookings.create() Так Так, у межах наявного залишку, поки організація продає клієнтам
sales.list() , sales.get() , sales.create() Так Ні
Товари на продаж зберігаються окремо від товарів для оренди: `inventory.list()`, доступність і `categories.list()` ніколи їх не повертають. ## З публічним ключем Вітрина може показувати товари на продаж і давати клієнтам додавати їх до запиту на бронювання так само, як це робить [клієнтський портал](https://requiply.com/docs/uk/guides/online-booking/booking-flow) на кроці **Додати товари для покупки**. Публічний ключ отримує до них доступ, лише поки організація **продає клієнтам**, для чого потрібні всі три умови: - функція «Продажі» на тарифі Advanced, як описано вище; - увімкнений **Продаж товарів** у [налаштуваннях клієнтського порталу](https://requiply.com/docs/uk/guides/online-booking/portal-settings#%D0%B4%D1%96%D1%97); - щонайменше один товар на продаж, який не архівовано. Інакше виклик викидає `403` з `reason` `selling_disabled`, тож вітрина може приховати розділ товарів. З публічним ключем: - `saleItems.list()` повертає лише активні товари, незалежно від `filter`. `barcode` і `purchaseCost` завжди `null`. - `saleItems.get()` повертає `404` для архівованого товару, а `soldUnits30d`, `revenue30d`, `soldUnitsTotal` дорівнюють `0`. - `saleLines` не може запитувати більше за `stockOnHand`. Рядок понад залишок викидає `409` з `reason` `out_of_stock`; `data.saleItemId` називає товар, а `data.availableQuantity` показує, скільки залишилося (`0`, коли все продано). ```ts try { await requiply.pricing.quote({ startDate, endDate, items, saleLines }); } catch (error) { if (error instanceof RequiplyError && error.reason === 'out_of_stock') { showNotice(`Only ${error.data?.availableQuantity} left`); } else if (error instanceof RequiplyError && error.reason === 'selling_disabled') { hideGoodsSection(); } else { throw error; } } ``` ## `saleItems.list()` ```ts saleItems.list( params?: SaleItemsListParams, options?: RequiplyRequestOptions, ): Promise ``` Необовʼязкові параметри: `search` (назва, артикул чи штрихкод), `category` (ідентифікатор категорії), `filter` (за замовчуванням `active`, також `archived` або `all`; публічні ключі завжди отримують `active`), `limit` (від 1 до 100, за замовчуванням 25), `cursor`. ```ts const { items, nextCursor } = await requiply.saleItems.list({ search: 'battery' }); for (const item of items) { console.log(item.name, item.salePrice, item.currency, item.stockOnHand); } ```
Поле Що містить
id , name , sku , barcode Товар. sku і barcode можуть бути null ; для публічного ключа barcode завжди null .
categoryId , categoryName , imageUrl Можуть бути null .
salePrice , currency Фіксована ціна за одиницю у валюті організації.
stockOnHand Одиниці на полиці. Значення може бути відʼємним, коли продажі перевищили облікований залишок.
purchaseCost Чиста собівартість одиниці або null , якщо ключ не може керувати залишками. Для публічного ключа завжди null .
isArchived Архівовані товари продати не можна.
## `saleItems.get()` ```ts saleItems.get( saleItemId: string, options?: RequiplyRequestOptions, ): Promise ``` Повертає `saleItem` з наведеними вище полями, а також полями `soldUnits30d`, `revenue30d`, `soldUnitsTotal`. ```ts const { saleItem } = await requiply.saleItems.get(itemId); console.log(saleItem.soldUnits30d, saleItem.revenue30d); ``` ## `sales.list()` ```ts sales.list( params?: SalesListParams, options?: RequiplyRequestOptions, ): Promise ``` Перелічує продажі від найновіших, як окремі, так і повʼязані з бронюваннями. Необовʼязкові фільтри:
Параметр Дія
kind standalone або booking .
status completed або cancelled .
unpaid true для окремих продажів, за якими ще є заборгованість.
clientId Продажі одного клієнта.
soldFrom , soldTo Дата й час у форматі ISO 8601.
search Номер продажу, імʼя клієнта, email чи телефон, назва товару чи артикул.
limit , cursor Розмір сторінки (від 1 до 100, за замовчуванням 25) і nextCursor попередньої сторінки.
```ts const { sales, currency } = await requiply.sales.list({ kind: 'standalone', unpaid: true }); ``` Кожен продаж має такі поля: `id`; `saleOrgId` (номер продажу, який співробітники бачать у застосунку); `status`; `soldAt`; `total`; `returnedTotal`; `net` (сума мінус повернення); `paidAmount`; `balance`; `paymentMethod`; `paidAt`; `note`; клієнта; бронювання, до якого він належить (`reservationId`, `reservationOrgId`); `itemCount`; `itemsLabel`. `balance` показує, скільки ще винен окремий продаж. Для продажу в бронюванні це значення завжди `0`, бо його оплачують через бронювання. ## `sales.get()` ```ts sales.get( id: string | number, params?: { idKind?: 'internal' | 'org' }, options?: RequiplyRequestOptions, ): Promise ``` `id` є UUID продажу або номером продажу із застосунку з `idKind: 'org'`. ```ts const { sale } = await requiply.sales.get(12, { idKind: 'org' }); ``` Продаж також містить `lines` (товар, кількість, `returnedQuantity`, `unitPrice`, `lineTotal`), а також `returns` і `payments`. Для продажу в бронюванні `payments` належать бронюванню, бо бронювання стягує оренду й товари одним платежем. ## `sales.create()` ```ts sales.create( input: SaleCreateInput, options?: RequiplyRequestOptions, ): Promise ``` Записує окремий продаж, як [Новий продаж](https://requiply.com/docs/uk/guides/sales/new-sale) у застосунку. ```ts const { sale, stockWarnings, payment } = await requiply.sales.create({ lines: [{ saleItemId: itemId, quantity: 2 }], client: { name: 'Alex', email: 'customer@example.com' }, paymentMethod: 'monobank', note: 'Counter sale', }); if (payment?.paymentUrl) console.log('Pay here:', payment.paymentUrl); ```
Поле Правила
lines Обовʼязкове. Від 1 до 100 товарів, кожен щонайбільше один раз, із цілою кількістю, більшою за нуль. Кожен рядок продається за salePrice товару.
clientId або client Необовʼязкове. client зіставляється за email, потім за телефоном, а якщо збігу немає, створюється новий.
paymentMethod payOnPickup (за замовчуванням) або один з онлайн-способів ( monobank , liqpay , wayforpay , stripe ) з активною інтеграцією. liqpay потребує клієнта з email.
soldAt ISO 8601. За замовчуванням поточний момент.
note До 2000 символів.
Залишок зменшується одразу. Продаж може опустити залишок нижче нуля: його все одно буде записано, а `stockWarnings` перелічує кожен такий товар із його `stockOnHand` і залишком `after` після продажу. `payment` є очікуваним платежем, з якого починається продаж, із `paymentUrl` для онлайн-способу оплати. Відхилений продаж викидає `RequiplyError` з `reason` на кшталт `sale_item_archived`, `payment_method_unavailable` чи `client_email_required`. Повний перелік див. в [Обробка помилок](https://requiply.com/docs/uk/developers/typescript-sdk/error-handling#%D0%BF%D1%80%D0%B8%D1%87%D0%B8%D0%BD%D0%B8-%D0%BF%D0%BE%D0%BC%D0%B8%D0%BB%D0%BE%D0%BA). ## Товари в бронюванні `pricing.quote()` і `bookings.create()` приймають `saleLines`, щоб продати товари разом з орендою: ```ts const quote = await requiply.pricing.quote({ startDate: '2026-07-01T10:00:00', endDate: '2026-07-03T18:00:00', items: [{ groupId: cameraKitId, quantity: 1 }], saleLines: [{ saleItemId: memoryCardId, quantity: 2 }], }); console.log(quote.saleSubtotal, quote.lineSaleItems[0]?.stockAfter); ``` - Секретний ключ може продавати у відʼємний залишок, як це можуть робити співробітники в застосунку. Публічний ключ не може: див. [З публічним ключем](#%D0%B7-%D0%BF%D1%83%D0%B1%D0%BB%D1%96%D1%87%D0%BD%D0%B8%D0%BC-%D0%BA%D0%BB%D1%8E%D1%87%D0%B5%D0%BC). - Товари продаються за каталожною ціною, знижки та коригування до них ніколи не застосовуються. Їхня сума є `saleSubtotal` і вже входить у `total`. - `lineSaleItems` показує кожен товар зі `stockOnHand` і `stockAfter`, тож можна попередити, перш ніж залишок стане відʼємним. - У `bookings.create()` залишок зменшується під час створення бронювання і повертається, якщо бронювання скасують. Сума товарів додається до `totalCost` бронювання та його оплати. - `bookings.get()` повертає товари як `saleItems`, а їхній продаж як `saleId`. Щоб змінити товари в наявному бронюванні, скористайтеся [Продажем товарів у бронюванні](https://requiply.com/docs/uk/guides/bookings/sell-items) в застосунку. ## Sitemap See the full [sitemap](https://requiply.com/docs/sitemap.md) for all pages.