Перейти до основного вмісту

Документи через API

Документи в API Skynum використовують для створення й оновлення замовлень, продажів, повернень, поставок, внутрішніх складських документів, виробництва, інвентаризацій і рахунків на оплату.

Це найбільш відповідальна частина API, тому що після активації документ може змінити залишки, резерви, очікування, собівартість, взаєморозрахунки, фінансові показники та аналітику.

Повʼязані інструкції:

Endpoint-и документів

МетодEndpointПризначення
GET/v1/documentsотримати список документів
POST/v1/documentsстворити документ
GET/v1/documents/:idотримати один документ
PUT/v1/documents/:idоновити документ
DELETE/v1/documents/:idвидалити документ
PUT/v1/documents/:id/activateактивувати документ
PUT/v1/documents/:id/deactivateдеактивувати документ
PUT/v1/documents/:id/change_statusзмінити статус документа
POST/v1/documents/:id/generateстворити новий документ з поточного
POST/v1/documents/:id/lazy_sale_returnстворити повернення продажу спрощеним способом

Типи документів

Тип документа передається у полі typedoc. Для POST /v1/documents це обовʼязкове поле.

API документів підтримує такі типи:

typedocНазва в SkynumПризначення
client_orderЗамовлення покупцяРезервує товари для покупця і може бути виконане продажем.
saleТоварна накладнаФіксує продаж товарів покупцю.
sale_returnПовернення продажуПовертає товари від покупця після продажу.
retailПродаж роздрібнийДокумент роздрібного продажу, зокрема зі Skynum.Каса.
retail_returnПовернення роздрібного продажуПовернення роздрібного продажу.
payment_invoiceРахунок на оплатуРахунок для покупця без списання товарів зі складу.
price_listПрайс-листДокумент для роботи з цінами.
supplier_orderЗамовлення постачальникуФормує очікування товарів від постачальника.
receiptНадходження від постачальникаОприбутковує товари від постачальника.
receipt_returnПовернення постачальникуПовертає товари постачальнику.
surplusОприбуткуванняОприбутковує товар без контрагента.
product_offСписанняСписує товари зі складу.
movementПереміщенняПереміщує товари між складами.
manufactureВиробництво продукціїВиробничий документ для списання матеріалів і випуску продукції.
disassemblyРозукомплектаціяЗворотний процес до виробництва або комплектації.
inventoryІнвентаризаціяДокумент інвентаризації.

Інші типи документів платформи не слід використовувати в API V1, якщо вони не входять у цей список.

Чернетка, активність, стан і статус

У документах важливо розрізняти чотири речі:

ПолеЩо означає
activeЧи активований документ. Неактивний документ є чернеткою і не проводить облікові зміни.
docstateСистемний стан документа. Він відображає бізнес-етап документа.
status_idСтатус із налаштувань компанії. Статуси налаштовуються користувачами, але привʼязані до системних станів.
typedocТип документа, від якого залежить його облікова логіка.

Після створення документ зберігається як чернетка. Щоб документ почав впливати на облік, його потрібно активувати або створити одразу з activate: true.

попередження

Не плутайте статус і стан. status_id - це конкретний статус компанії, а docstate - системний стан, який визначає логіку документа.

Системні стани документів

Загальні стани для більшості документів:

docstateЛюдська назва
createdНовий
activatedАктивований
generatedУ процесі
completedВиконаний
partially_completedЧастково виконано
canceledСкасовано

Для замовлення покупця використовуються окремі назви станів:

docstateЛюдська назва
createdНовий
activatedРезерв оформлений
generatedПродаж створений
partially_completedЧастково виконано
completedПродаж завершений
canceledСкасовано

Для замовлення постачальнику:

docstateЛюдська назва
createdНовий
activatedАктивований
generatedПрихід створений
completedПрихід завершений
partially_completedЧастково виконано
canceledСкасовано

Для виробництва:

docstateЛюдська назва
createdНове
reservedЗарезервовано
manufacturingМатеріали списані
activatedЗавершено

Отримання списку документів

GET /v1/documents повертає список документів. Параметр typedoc є обовʼязковим.

Підтримані фільтри:

ПараметрПризначення
typedocТип документів. Обовʼязковий.
offsetСторінка або зміщення списку. За замовчуванням 1.
limitКількість записів. За замовчуванням 100, максимум 1000.
date_fromДата документа від.
date_toДата документа до.
queryПошук за номером документа або кодом.
stock_idФільтр за складом.
contragent_idФільтр за контрагентом.
payment_subject_idФільтр за субʼєктом платежу, якщо документ повʼязаний з фінансовим сценарієм.
payment_subject_typeТип субʼєкта платежу для такого фільтра.
typepayФільтр за типом оплати документа.
activeФільтр за активністю.
status_idФільтр за статусом.
with_custom_fieldsДодати у відповідь додаткові поля.
updated_fromОновлено від.
updated_toОновлено до.

Приклад:

GET /v1/documents?typedoc=client_order&limit=100&updated_from=2026-05-01

Отримання одного документа

GET /v1/documents/:id повертає один документ за ID.

Додатково можна передати:

with_custom_fields=true

щоб отримати додаткові поля документа.

Створення документа

Мінімально для створення документа потрібен typedoc:

{
"document": {
"typedoc": "client_order"
}
}

На практиці для облікового документа зазвичай передають:

  • typedoc - тип документа;
  • docdate - дату документа;
  • stock_from_id або stock_to_id - склад, залежно від типу документа;
  • contragent або contragent_id через обʼєкт контрагента, якщо документ працює з покупцем або постачальником;
  • typepay - спосіб оплати документа;
  • typeprice - тип ціни;
  • currency_id, currency_rate, accounting_currency_rate - валютні параметри, якщо потрібні;
  • line_items - товарні рядки;
  • activate або окрему активацію після перевірки документа.

Приклад спрощеного замовлення покупця:

{
"document": {
"typedoc": "client_order",
"docdate": "2026-05-12",
"stock_from_id": "stock-id",
"typepay": "credit",
"typeprice": "price_retail",
"contragent": {
"id": "contragent-id"
},
"line_items": [
{
"product_id": "product-id",
"quantity": 2,
"price": 500
}
]
}
}

Поля для створення й оновлення документа

ПолеПризначення
idВнутрішній ID документа. Використовується для наявного документа, коли інтеграція передає вже відомий запис.
typedocТип документа. Обовʼязкове поле для створення.
docdateДата документа.
product_off_dateДата списання товарів або матеріалів, якщо вона використовується в сценарії документа.
docnumНомер документа.
codeКод документа.
api_idЗовнішній ID інтеграції.
api_numberЗовнішній номер інтеграції.
descriptionОпис або примітка до документа.
filial_idФілія або юридична особа.
sale_channel_idКанал продажів.
owner_idВласник документа.
executor_idВиконавець документа.
status_idСтатус документа.
currency_idВалюта документа.
currency_rateКурс валюти документа.
accounting_currency_rateОбліковий курс валюти.
stock_from_idСклад, з якого списуються товари.
stock_to_idСклад, на який надходять товари.
typepriceТип ціни в документі.
typepayТип оплати документа.
cashbox_idКаса для оплати готівкою.
bankbox_idБанківський рахунок для безготівкової або карткової оплати.
paid_by_cashСума оплати готівкою.
paid_by_cardСума оплати карткою.
paid_by_bonusСума оплати бонусами.
payment_due_dateТермін оплати.
payment_method_idСпосіб оплати, якщо він використовується у сценарії документа.
disable_autobindВимкнути автоматичне звʼязування платежів.
due_dateТермін виконання документа.
amount_discountЗагальна знижка документа.
amount_markupЗагальна націнка документа.
perform_amount_roundingОкруглення суми документа.
supplier_price_recalculationПерерахунок цін постачальника.
activateАктивувати документ після створення або оновлення.
target_document_pay_attributesПараметри оплати для документа, який система створює під час зміни статусу.
deliveryДані доставки.
line_itemsТоварні рядки.
bindsЗвʼязки документа з платежами.
commentsКоментарі.
custom_fieldsДодаткові поля.

Поля короткої відповіді документа

GET /v1/documents повертає список документів у короткому форматі.

ПолеЩо означає
idВнутрішній ID документа.
api_idЗовнішній ID інтеграції.
api_numberЗовнішній номер інтеграції.
typedocТип документа.
docnumНомер документа в Skynum.
codeКод документа.
user_idКористувач, повʼязаний з документом.
descriptionОпис документа.
typepayТип оплати документа.
typepriceТип ціни документа.
docstateСистемний стан документа.
filial_idФілія або юридична особа.
executor_idВиконавець документа.
owner_idВласник документа.
status_idСтатус документа.
contragent_idКонтрагент документа.
currency_idВалюта документа.
stock_to_idСклад надходження.
stock_from_idСклад списання або резерву.
sale_channel_idКанал продажів.
activeЧи активований документ.
amountЗагальна сума документа.
docdateДата документа.
product_off_dateДата списання товарів або матеріалів.
due_dateТермін виконання.
payment_due_dateТермін оплати.
custom_fieldsДодаткові поля, якщо передано with_custom_fields=true.
created_atДата створення.
updated_atДата оновлення.

Поля повної відповіді документа

GET /v1/documents/:id і write-запити повертають повніший обʼєкт документа.

ПолеЩо означає
idВнутрішній ID документа.
api_idЗовнішній ID інтеграції.
api_numberЗовнішній номер інтеграції.
typedocТип документа.
docnumНомер документа в Skynum.
codeКод документа.
user_idКористувач, повʼязаний з документом.
owner_idВласник документа.
executor_idВиконавець документа.
descriptionОпис документа.
typepayТип оплати документа.
typepriceТип ціни документа.
docstateСистемний стан документа.
filial_idФілія або юридична особа.
source_document_idДокумент-джерело, якщо документ створений на підставі іншого документа.
perform_amount_roundingЧи застосовується округлення суми.
supplier_price_recalculationЧи використовується перерахунок цін постачальника.
cashbox_idКаса документа.
bankbox_idБанківський рахунок документа.
sale_channel_idКанал продажів.
docdateДата документа.
product_off_dateДата списання.
activeЧи активований документ.
status_idID статусу.
status_titleНазва статусу.
currency_idID валюти.
currency_titleНазва валюти.
currency_codeКод валюти.
stock_to_idID складу надходження.
stock_to_titleНазва складу надходження.
stock_from_idID складу списання або резерву.
stock_from_titleНазва складу списання або резерву.
currency_rateКурс валюти документа.
accounting_currency_rateОбліковий курс валюти.
amountЗагальна сума документа.
amount_roundingСума округлення.
amount_productsСума товарних рядків без загальних знижок і націнок.
amount_products_discountСума знижок у товарних рядках.
amount_discountЗагальна знижка документа.
amount_markupЗагальна націнка документа.
amount_contragentСума взаєморозрахунків з контрагентом.
amount_ndsСума ПДВ.
amount_nettoСума без ПДВ.
paid_by_cashОплата готівкою.
paid_by_bonusОплата бонусами.
paid_by_cardОплата карткою.
due_dateТермін виконання.
payment_due_dateТермін оплати.
contragentКороткі дані контрагента.
deliveryДані доставки.
line_itemsТоварні рядки.
commentsКоментарі.
target_documentsДокументи, створені з поточного.
bindsЗвʼязки документа з платежами.
custom_fieldsДодаткові поля, якщо передано with_custom_fields=true.
created_atДата створення.
updated_atДата оновлення.

Типи оплати документа

Поле typepay описує, як документ має бути оплачений.

typepayНазва
paidсплачено
creditкредит
freeбезоплатно

Для документів продажу або поставки вибір typepay впливає на те, чи потрібна оплата, чи виникає заборгованість, чи документ проводиться як безоплатний або особливий сценарій.

Типи цін у документі

У полі typeprice для документів використовуються такі значення:

typepriceНазва
price_balanceОблікова ціна
price_supplyЦіна прихідна
price_retailЦіна роздрібна
price_wholesaleЦіна гуртова
price_promoЦіна перекреслена
примітка

У товарах для запису перекресленої ціни використовується поле price_old, а в документах для вибору типу ціни використовується значення price_promo.

Товарні рядки

Товарні рядки передаються в масиві line_items.

Поля рядка для створення або оновлення:

ПолеПризначення
idID товарного рядка для оновлення наявного рядка.
api_idЗовнішній ID товарного рядка.
_destroyПозначка видалення рядка під час оновлення документа.
product_idВнутрішній ID товару.
product_codeКод товару.
product_skuАртикул товару.
product_api_idЗовнішній ID товару.
modification_idВнутрішній ID модифікації.
modification_codeКод модифікації.
modification_skuАртикул модифікації.
modification_api_idЗовнішній ID модифікації.
measure_idОдиниця виміру.
quantityКількість.
priceЦіна рядка.
discountЗнижка в рядку.
serialsСерійні номери.
nds_rateСтавка ПДВ у рядку.
price_supplyПрихідна ціна.
price_retailРоздрібна ціна.
price_wholesaleГуртова ціна.
amount_expensesВитрати, віднесені на товарний рядок.

Товар у рядку можна ідентифікувати різними способами: через внутрішній product_id, код, артикул або зовнішній product_api_id. Для модифікацій так само можна передавати внутрішній ID, код, артикул або зовнішній modification_api_id.

Поля товарного рядка у відповіді

ПолеЩо означає
idID товарного рядка.
api_idЗовнішній ID рядка.
codeКод рядка.
product_idID товару.
product_titleНазва товару.
product_codeКод товару.
product_skuАртикул товару.
product_api_idЗовнішній ID товару.
product_international_codeМіжнародний код товару.
category_idID категорії товару.
category_titleНазва категорії товару.
kingroup_idID спорідненої групи товару.
kingroup_codeКод спорідненої групи товару.
kingroup_titleНазва спорідненої групи товару.
quantityКількість.
priceЦіна рядка.
price_supplyПрихідна ціна.
price_retailРоздрібна ціна.
price_wholesaleГуртова ціна.
price_nettoЦіна без ПДВ.
nds_rateСтавка ПДВ.
discountЗнижка рядка.
amountСума рядка.
amount_ndsСума ПДВ у рядку.
amount_nettoСума без ПДВ.
amount_supplyСума в прихідних цінах.
amount_retailСума в роздрібних цінах.
amount_wholesaleСума в гуртових цінах.
measure_idID одиниці виміру.
measure_titleНазва одиниці виміру.
modification_idID модифікації.
modification_titleНазва модифікації.
modification_codeКод модифікації.
modification_skuАртикул модифікації.
modification_api_idЗовнішній ID модифікації.
amount_expensesВитрати, віднесені на рядок.
datevalidТермін придатності.
notesПримітка до рядка.
serialsСерійні номери, якщо товар ведеться за серійними номерами.
created_atДата створення.
updated_atДата оновлення.
попередження

Якщо товар має модифікації, серійні номери, партії або терміни придатності, інтеграція має передавати дані так, щоб документ відповідав реальному обліку. Інакше документ може не активуватися або провести облік не так, як очікується.

Контрагент у документі

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

Контрагент передається обʼєктом contragent, наприклад:

{
"contragent": {
"id": "contragent-id",
"code": "100",
"title": "Покупець",
"phone": "+380777777777",
"email": "[email protected]",
"discount_card": null,
"group_id": null
}
}

Якщо контрагент уже є в Skynum, найнадійніше передавати його id. Якщо інтеграція створює або оновлює контрагентів окремо, використовуйте контрагентів через API.

Поля contragent, які приймає документ:

ПолеПризначення
idID наявного контрагента.
codeКод контрагента.
phoneТелефон.
emailEmail.
discount_cardДисконтна картка.
addressАдреса контрагента.
group_idГрупа контрагента.
titleНазва або імʼя контрагента.
status_idСтатус контрагента.
entity_typeТип особи або компанії.
bank_idБанк.
bank_accountБанківський рахунок.
taxnumberПодатковий номер.
remarkПримітка.
instagramInstagram.
currency_idВалюта контрагента.

Доставка в документі

Поле delivery використовується для даних доставки.

Поля доставки для створення або оновлення:

ПолеПризначення
kindСпосіб доставки.
planned_dateПланова дата доставки або відправлення.
notesПримітки до доставки.
costВартість доставки.
recipient_first_nameІмʼя отримувача.
recipient_last_nameПрізвище отримувача.
recipient_middle_nameПо батькові отримувача.
recipient_phoneТелефон отримувача.
provider_waybill_idID експрес-накладної у службі доставки.
provider_registry_idID реєстру у службі доставки.
waybill_numberНомер експрес-накладної.
payer_typeПлатник доставки.
estimated_dateОрієнтовна дата доставки.
cost_to_document_amountЧи додавати вартість доставки до суми документа.
cargo_typeТип вантажу.
shipment_notesОпис або примітка для відправлення.
evaluation_amountОціночна вартість.
customize_seatsЧи налаштовуються місця відправлення вручну.
seats_quantityКількість місць.
volumeОбʼєм відправлення.
weightВага відправлення.
auto_evaluation_amountАвтоматично визначати оціночну вартість.
payment_methodСпосіб оплати доставки.
backward_delivery_enabledЧи ввімкнена зворотна доставка.
payment_control_enabledЧи ввімкнений контроль оплати.
backward_payerПлатник зворотної доставки.
backward_amountСума зворотної доставки або післяплати.
payment_control_amountСума контролю оплати.
sender_address_idАдреса відправника.
sender_employee_idКонтактна особа відправника.
sender_phoneТелефон відправника.
seatsМасив місць відправлення.
recipient_addressАдреса отримувача.

У seats можна передавати:

ПолеПризначення
widthШирина місця.
lengthДовжина місця.
heightВисота місця.
weightВага місця.
volume_weightОбʼємна вага.
service_no_boxОзнака відправлення без коробки служби доставки.

У recipient_address можна передавати:

ПолеПризначення
idID адреси.
api_idЗовнішній ID адреси.
phoneТелефон адресата.
recipient_nameІмʼя отримувача у старому форматі адреси.
nameНазва або імʼя у старому форматі адреси.
addressАдреса у старому форматі.
post_officeВідділення у старому форматі.
global_city_idМісто з глобального довідника.
global_post_office_idВідділення з глобального довідника.
global_street_idВулиця з глобального довідника.
novaposhta_city_idМісто Нової пошти.
novaposhta_post_office_idВідділення Нової пошти.
novaposhta_street_idВулиця Нової пошти.
address_lineАдресний рядок.
street_nameНазва вулиці.
houseБудинок.
flatКвартира або офіс.
postal_codeПоштовий індекс.
notesПримітки до адреси.
primaryОсновна адреса контрагента.
save_contragent_addressЗберегти адресу в картці контрагента.

Докладніше про адреси та поля Нової пошти: адреси доставки, поля Нової пошти.

Додаткові поля

Додаткові поля передаються у custom_fields. Ключем є ID додаткового поля.

Приклад:

{
"custom_fields": {
"field-id-1": true,
"field-id-2": "Текст",
"field-id-3": 15,
"field-id-4": "term-id"
}
}

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

Докладніше: додаткові поля.

Оновлення документа

PUT /v1/documents/:id оновлює документ.

Для оновлення документа можна використовувати:

  • activate - активувати документ після оновлення;
  • status_id - змінити статус після оновлення;
  • target_document_pay_attributes - параметри оплати для автоматично створеного вихідного документа.
попередження

Не передавайте activate і status_id в одному запиті. Якщо передати activate: true, документ буде активований, а сценарій зміни статусу в цьому запиті не виконається.

Активація документа

Endpoint:

PUT /v1/documents/:id/activate

Активація проводить документ в обліку. Залежно від typedoc, це може:

  • зарезервувати товар;
  • списати товар;
  • оприбуткувати товар;
  • створити очікування поставки;
  • змінити собівартість;
  • вплинути на взаєморозрахунки;
  • оновити аналітичні звіти.

Також документ можна створити або оновити з:

{
"document": {
"activate": true
}
}

Деактивація документа

Endpoint:

PUT /v1/documents/:id/deactivate

Деактивація скасовує проведення документа, якщо це дозволено поточним станом обліку.

Деактивація може бути неможливою або небажаною, якщо:

  • документ має повʼязані документи;
  • документ має повʼязані платежі;
  • після документа вже були наступні облікові операції;
  • документ впливає на партії, серійні номери, виробництво або інвентаризацію;
  • зміна зламає залишки, собівартість або взаєморозрахунки.

Зміна статусу документа

Endpoint:

PUT /v1/documents/:id/change_status

У тілі запиту передається status_id:

{
"document": {
"status_id": "status-id"
}
}

Для сценаріїв, де зміна статусу створює вихідний документ, можна передати pay_attributes:

{
"document": {
"status_id": "status-id",
"pay_attributes": {
"typepay": "credit",
"payment_due_date": "10.02.2025",
"cashbox_id": null,
"bankbox_id": null,
"paid_by_cash": 0,
"paid_by_card": 0,
"paid_by_bonus": 0
}
}
}

Це корисно, наприклад, коли замовлення покупця переводиться у стан виконання і система створює документ продажу.

Створення документа з документа

Endpoint:

POST /v1/documents/:id/generate

У тілі передається:

{
"document": {
"target_typedoc": "sale"
}
}

Система створює новий документ з поточного. Товари й основні поля копіюються з документа-джерела, а в новому документі встановлюється source_document_id.

Типовий сценарій - створити продаж із замовлення або інший повʼязаний документ за логікою Skynum.

Спрощене повернення продажу

Endpoint:

POST /v1/documents/:id/lazy_sale_return

Endpoint виконує такі дії:

  • створює і активує sale_return;
  • працює тільки з client_order і sale;
  • товари копіюються з документа продажу;
  • оплата береться така сама, як у продажі;
  • якщо повернення продажу вже існує, endpoint нічого не змінює і повертає успішну відповідь.
попередження

Перед використанням lazy_sale_return інтеграція має точно знати, який документ є джерелом повернення. Це не універсальний endpoint для будь-якого повернення.

Звʼязки з платежами

Документ може мати binds - звʼязки з платежами.

Для binds використовується така структура:

[
{
"bind_id": "payment-id",
"amount": 200
}
]

bind_id вказує ID активованого платежу, а amount - яку суму потрібно розподілити.

Платіж у binds має відповідати документу: дата платежу не повинна бути пізнішою за дату документа, контрагент, філія і валюта мають збігатися, а сума звʼязку має бути більшою за нуль.

Докладніше: Платежі через API, повʼязані платежі.

Безпечний порядок роботи

Для інтеграцій із документами рекомендований такий порядок:

  1. Отримати або створити довідники: товари, контрагентів, склади, додаткові поля.
  2. Створити документ як чернетку без activate.
  3. Перевірити відповідь API: id, typedoc, amount, line_items, contragent, склад, валюту.
  4. За потреби оновити документ.
  5. Активувати документ окремим запитом.
  6. Отримати документ повторно і перевірити active, docstate, суми й звʼязки.
порада

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

Чеклист перед запуском

Перед запуском інтеграції з документами перевірте:

  • які typedoc створює інтеграція;
  • які склади використовуються у stock_from_id і stock_to_id;
  • як інтеграція знаходить товар: product_id, product_code, product_sku або product_api_id;
  • чи потрібні модифікації, серійні номери, партії або терміни придатності;
  • чи передається контрагент там, де він потрібен;
  • як передаються оплата, борг або термін оплати;
  • чи потрібні статуси і переходи між станами;
  • чи є черга write-запитів, щоб не отримувати Concurrent write locked;
  • чи не дублюються документи при повторній відправці з зовнішньої системи;
  • хто відповідає за помилки активації й повторну синхронізацію.

Підсумок

Документи через API потрібно створювати обережно: спочатку правильно визначити typedoc, склад, контрагента, товарні рядки, оплату й статус, а вже потім активувати документ. Неактивний документ є чернеткою, активований документ змінює облік.