Bookkeeper API

Appearance

On this page

/document ​

Кінцева точка /document відповідає за роботу з документами.

Методи ​

  • /document/index - завантажити перелік документів
  • /document/load - завантажити документ
  • /document/update - створити або оновити документ
  • /document/setdone - провести або розпровести документ
  • /document/getdone - перевірити проведеність документа
  • /document/linkto - пов'язати два документи
  • /document/pdf - отримати друковану форму документа (PDF)

GET /document/index/?{from}&{to}&{pageSize=100}&{offset=0} ​

Завантажує перелік документів за період.

Параметри запиту:

  • from - початок періоду (дата документа), формат 2026-01-01. Обов'язковий.
  • to - кінець періоду. Обов'язковий.
  • pageSize - розмір сторінки (1-100).
  • offset - зміщення ( > 0)
  • dateModified - необов'язковий фільтр: тільки документи, змінені починаючи з вказаної дати/часу. Зручно для інкрементальної синхронізації.
  • agent - необов'язковий фільтр: UID контрагента. Повертаються тільки документи цього контрагента. Якщо контрагента з таким UID немає - повертається пустий перелік.

Приклад: /document/index?from=2026-09-01&to=2026-09-30&agent=d362cdfd-72d5-4906-889c-44152121c8b4

Повертає стандартну відповідь для індексу об'єктів Document (без рядків документів).

javascript
{
   "success" : true, 
   "totalCount": 10,
   "data": [ /* Document */
		{ "uid": "...." }
	]
};
{
   "success" : true, 
   "totalCount": 10,
   "data": [ /* Document */
		{ "uid": "...." }
	]
};

Зверніть увагу, що поле totalCount поверне загальну кількість документів за період (з урахуванням фільтрів dateModified та agent).

GET /document/load/{uid} ​

Завантажує документ по його UID.

Параметри запиту:

  • uid - UID документа (в URL)

Повертає стандартну відповідь з об'єктом Document, включно з рядками (details), складами (storeIn, storeOut), ознакою проведеності (done), прапорцем «ПДВ в т.ч.» (vatInPrice), зв'язком з батьківським документом (parent), якщо він встановлений, та показниками paid / shipped (оплачено / відвантажено за пов'язаними проведеними документами).

json
{
   "success" : true, 
   "data": { /* Document */
		"uid": "...."
	}
};
{
   "success" : true, 
   "data": { /* Document */
		"uid": "...."
	}
};

POST /document/update ​

Створює або оновлює властивості документа.

Тіло запита має бути обєктом Document:

json
{
    "uid":"C259B17B-BFC8-48B9-A6A7-CEB1FD054413",
    "date":"2023-02-23",
    "type": "Invoice",
    "no":"string",
    "sum": 100,
    "vatCode": "20",
    "vatInPrice": true,
    "memo": "string",
    "agent": {
        "uid": "d362cdfd-72d5-4906-889c-44152121c8b4",
        "name": "string",
    },
    "details": [
        {
            "uid": "334D0E63-3091-4C94-AB1D-0B240B43BBC5",
            "entity":{
                "uid": "374BA375-75CF-4C94-BBF7-51C3F8F81534",
                "kind": "goods",
                "name": "string"
            },
            "qty":"1",
            "price":"10",
            "sum": "10",
            "memo": "string" 
        }
    ]
}
{
    "uid":"C259B17B-BFC8-48B9-A6A7-CEB1FD054413",
    "date":"2023-02-23",
    "type": "Invoice",
    "no":"string",
    "sum": 100,
    "vatCode": "20",
    "vatInPrice": true,
    "memo": "string",
    "agent": {
        "uid": "d362cdfd-72d5-4906-889c-44152121c8b4",
        "name": "string",
    },
    "details": [
        {
            "uid": "334D0E63-3091-4C94-AB1D-0B240B43BBC5",
            "entity":{
                "uid": "374BA375-75CF-4C94-BBF7-51C3F8F81534",
                "kind": "goods",
                "name": "string"
            },
            "qty":"1",
            "price":"10",
            "sum": "10",
            "memo": "string" 
        }
    ]
}

Зверніть увагу:

  • Непередані властивості не змінюються (див. Особливості оновлення). Зокрема, якщо не передати sum або details - сума та рядки документа залишаться без змін. Явно переданий пустий масив "details": [] видаляє всі рядки.

  • Прапорець vatInPrice визначає, як трактуються ціни та суми (price, sum):

    • vatInPrice: true - «ПДВ в т.ч.»: ціни та суми передаються З ПДВ. Система сама виділяє суму ПДВ за ставкою vatCode (наприклад, sum 100 з vatCode "20" - це 83.33 без ПДВ + 16.67 ПДВ, разом 100).
    • vatInPrice: false або відсутній - ціни та суми передаються без ПДВ, сума ПДВ нараховується зверху за ставкою vatCode.

    Відповіді (load, index) симетричні: для документа з «ПДВ в т.ч.» суми повертаються з ПДВ - що передали, те й отримаєте.

  • Властивість done в цьому методі ігнорується. Для проведення документа використовуйте /document/setdone.

  • Проведений документ не можна оновлювати. Спочатку розпроведіть його.

Повертає стандартну відповідь з об'єктом Document.

json
{
   "success" : true, 
   "data": { /* Document */
		"uid": "...."
	}
}
{
   "success" : true, 
   "data": { /* Document */
		"uid": "...."
	}
}

Виготовлення ​

Документ «Виготовлення» (type: "manufacture", розділ «Запаси») має два види рядків в одному масиві details - їх розрізняє властивість kind:

  • "product" - готова продукція, оприбутковується на склад storeIn;
  • "material" - сировина, списується зі складу storeOut, або послуга, вартість якої включається до собівартості продукції.
json
{
    "uid":"C259B17B-BFC8-48B9-A6A7-CEB1FD054413",
    "date":"2026-09-30",
    "type": "manufacture",
    "storeOut": { "uid": "0E0B4E2C-6B0B-4B37-9C6A-6F3C0C1B7A11" },
    "storeIn": { "uid": "0E0B4E2C-6B0B-4B37-9C6A-6F3C0C1B7A11" },
    "details": [
        {
            "kind": "product",
            "entity": { "uid": "374BA375-75CF-4C94-BBF7-51C3F8F81534", "kind": "product", "name": "string" },
            "qty": 2
        },
        {
            "kind": "material",
            "entity": { "uid": "9F3A1D52-3C0E-4E0A-8C55-2B7E1A0D4F10" },
            "qty": 4
        }
    ]
}
{
    "uid":"C259B17B-BFC8-48B9-A6A7-CEB1FD054413",
    "date":"2026-09-30",
    "type": "manufacture",
    "storeOut": { "uid": "0E0B4E2C-6B0B-4B37-9C6A-6F3C0C1B7A11" },
    "storeIn": { "uid": "0E0B4E2C-6B0B-4B37-9C6A-6F3C0C1B7A11" },
    "details": [
        {
            "kind": "product",
            "entity": { "uid": "374BA375-75CF-4C94-BBF7-51C3F8F81534", "kind": "product", "name": "string" },
            "qty": 2
        },
        {
            "kind": "material",
            "entity": { "uid": "9F3A1D52-3C0E-4E0A-8C55-2B7E1A0D4F10" },
            "qty": 4
        }
    ]
}

Зверніть увагу:

  • kind обов'язковий для кожного рядка; рядок без нього не приймається.
  • У відповіді рядки впорядковані: спочатку готова продукція, потім сировина.
  • agent, contract, vatCode, vatInPrice для цього документа не використовуються.
  • Ціни та суми розраховуються при проведенні, передавати їх не обов'язково: сировина списується за собівартістю партій, а сума документа та готової продукції дорівнює сумі списаної сировини і послуг. Значення price / sum, передані в запиті, після проведення будуть замінені розрахованими.
  • Для проведення мають бути вказані обидва склади (storeOut та storeIn; це може бути один і той самий склад), хоча б один рядок сировини, кількість готової продукції більша за нуль, а сировини на складі storeOut має вистачати. Один об'єкт обліку не може повторюватись серед рядків одного виду.

POST /document/setdone ​

Проводить (done: true) або розпроводить (done: false) документ.

Виконується та сама операція, що й кнопки «Провести» / «Розпровести» в інтерфейсі, з тими самими наслідками: для видаткової накладної - списання залишків складу та рух по регістрах, для рахунку - встановлення статусу, перерахунок показників «оплачено/відвантажено» пов'язаного рахунку тощо.

Тіло запита:

json
{
    "uid":"c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
    "done": true
}
{
    "uid":"c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
    "done": true
}

Повертає стандартну відповідь з поточним станом документа:

json
{
   "success" : true, 
   "data": {
		"uid": "c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
		"done": true
	}
}
{
   "success" : true, 
   "data": {
		"uid": "c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
		"done": true
	}
}

Зверніть увагу:

  • Метод ідемпотентний: повторний виклик для документа, який вже знаходиться в потрібному стані, не є помилкою.
  • Документ без рядків провести не можна.
  • Не можна розпровести документ, у якого є проведені дочірні документи.
  • Для проведення та розпроведення користувачу API потрібні ролі з відповідними правами. Ролі призначає адміністратор облікового запису в особистому кабінеті: Логіни → (користувач для API) → Фірми та дозволи.

GET /document/getdone/{uid} ​

Перевіряє проведеність документа по його UID.

Параметри запиту:

  • uid - UID документа (в URL)
json
{
   "success" : true, 
   "data": {
		"uid": "c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
		"done": false
	}
}
{
   "success" : true, 
   "data": {
		"uid": "c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
		"done": false
	}
}

POST /document/linkto ​

Пов'язує два документа. Зверніть увагу, що звязувати можна як звичайні (Document), так і платіжні документи (PayDocument).

Тіло запита має бути обєктом DocumentLink:

json
{
    "uid":"c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
    "parent":"d362cdfd-72d5-4906-889c-44152121c8b4"
}
{
    "uid":"c259b17b-bfc8-48b9-a6a7-ceb1fd054413",
    "parent":"d362cdfd-72d5-4906-889c-44152121c8b4"
}

Напрямок зв'язку: uid - дочірній документ, parent - батьківський. Наприклад, для пари «рахунок → видаткова накладна» батьківським є рахунок:

json
{
    "uid":"<uid видаткової накладної>",
    "parent":"<uid рахунку>"
}
{
    "uid":"<uid видаткової накладної>",
    "parent":"<uid рахунку>"
}

Зверніть увагу:

  • Метод ідемпотентний: повторний виклик для тієї ж пари не створює дубль.
  • Документ має одного батька: виклик з іншим parent перезаписує зв'язок.
  • Встановлений зв'язок повертається у властивості parent дочірнього документа в /document/load.
  • Після зв'язування перераховуються показники paid / shipped батьківського документа (а при перелінковці - і попереднього). Тому порядок викликів setdone та linkto не має значення: статуси рахунку («Очікує оплати» / «Очікує відвантаження») оновляться в обох випадках.

Повертає стандартну відповідь з пустим об'єктом даних

json
{
   "success" : true, 
   "data": {
	}
}
{
   "success" : true, 
   "data": {
	}
}

GET /document/pdf/{uid}?{form} ​

Повертає друковану форму документа у форматі PDF - той самий файл, що формується в інтерфейсі командою «Експортувати → … Adobe PDF».

Параметри запиту:

  • uid - UID документа (в URL)
  • form - код друкованої форми (необов'язковий). Без цього параметра повертається основна форма виду документа (для рахунку - рахунок, для видаткової накладної - видаткова накладна). Для видаткової накладної також доступна складська накладна: ?form=WBWH.

Відповідь - файл application/pdf (без стандартного JSON-конверта).

У випадку помилки повертається JSON з відповідним HTTP-статусом:

  • 404 - документ або друкована форма не знайдені
  • 502 - помилка сервісу друкованих форм
json
{
   "success" : false, 
   "errors": [ "..." ]
}
{
   "success" : false, 
   "errors": [ "..." ]
}

Copyright © 2020-2023 Oleksandr Kukhtin & Bookkeeper SaaS LLC