Довідники через API
Довідники через API потрібні, щоб інтеграція передавала в документи, платежі, товари й звіти правильні ID: склади, філії, каси, банківські рахунки, статуси, податки, виробників, одиниці виміру, локації та канали продажів.
Не підставляйте назви довідників замість ID. Для надійної інтеграції спочатку отримайте потрібний довідник через API, збережіть ID і використовуйте саме його в товарах, документах, платежах або звітах.
Endpoint-и довідників
| Ресурс | Endpoint-и | Запис |
|---|---|---|
| Статуси | GET /v1/statuses, GET /v1/statuses/:id | тільки читання |
| Філії та юридичні особи | GET /v1/filials, GET /v1/filials/:id | тільки читання |
| Банки | GET /v1/banks, GET /v1/banks/:id | тільки читання |
| Банківські рахунки | GET /v1/bankboxes, GET /v1/bankboxes/:id | тільки читання |
| Каси | GET /v1/cashboxes, GET /v1/cashboxes/:id | тільки читання |
| Способи оплати | GET /v1/payment_methods, GET /v1/payment_methods/:id | тільки читання |
| Статті витрат | GET /v1/expenses, GET /v1/expenses/:id | тільки читання |
| Засновники | GET /v1/founders, GET /v1/founders/:id | тільки читання |
| Канали продажів | GET /v1/sale_channels, GET /v1/sale_channels/:id | тільки читання |
| Податки | GET /v1/taxes, GET /v1/taxes/:id | тільки читання |
| Локації | GET /v1/locations, GET /v1/locations/:id, POST /v1/locations, PUT /v1/locations/:id | читання і запис |
| Одиниці виміру | GET /v1/measures, GET /v1/measures/:id, POST /v1/measures, PUT /v1/measures/:id | читання і запис |
| Виробники | GET /v1/producers, GET /v1/producers/:id, POST /v1/producers, PUT /v1/producers/:id | читання і запис |
Статуси
Статуси використовуються в документах, платежах, контрагентах та інших процесах. У статусу важливий не тільки текст, а й системний стан, тому інтеграція має зберігати id, kind і state.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/statuses | отримати список статусів |
| GET | /v1/statuses/:id | отримати один статус |
Параметри списку:
| Параметр | Призначення |
|---|---|
kind | Тип обʼєкта, для якого потрібні статуси. |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID статусу. |
title | Назва статусу. |
kind | Тип обʼєкта, до якого належить статус. |
state | Системний стан статусу. |
color | Колір статусу. |
ord | Черговість статусу. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Філії та юридичні особи
Філії використовуються у складах, касах, банківських рахунках, документах, платежах і звітах. Якщо компанія веде облік по кількох юридичних особах або філіях, інтеграція має передавати правильний filial_id.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/filials | отримати список філій |
| GET | /v1/filials/:id | отримати одну філію |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID філії або юридичної особи. |
title | Назва. |
phone | Телефон. |
address | Адреса. |
egrpo | ЄДРПОУ. |
tax_number | Податковий номер. |
account | Рахунок. |
boss | Керівник. |
chief_accountant | Головний бухгалтер. |
cashier | Касир. |
bank_id | Банк. |
prime | Ознака головної компанії. |
use_prime_requisites | Використання реквізитів головної компанії. |
time_zone | Часовий пояс. |
use_nds | Чи використовується ПДВ. |
nds_id | Податкова ставка ПДВ. |
nds_only_realized | ПДВ тільки за реалізованими операціями. |
active | Чи активна філія. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Банки
Банки використовуються в банківських рахунках, реквізитах контрагентів і філій.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/banks | отримати список банків |
| GET | /v1/banks/:id | отримати один банк |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID банку. |
code | Код банку. |
title | Назва банку. |
address | Адреса банку. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Банківські рахунки
Банківські рахунки використовуються в безготівкових платежах, банківських виписках, конвертаціях і фінансових звітах.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/bankboxes | отримати список банківських рахунків |
| GET | /v1/bankboxes/:id | отримати один банківський рахунок |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID банківського рахунку. |
title | Назва рахунку. |
number | Номер рахунку. |
bank_id | Банк. |
currency_id | Валюта рахунку. |
filial_id | Філія або юридична особа. |
shared | Чи доступний рахунок спільно. |
active | Чи активний рахунок. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Каси
Каси використовуються для готівкових платежів, касових ордерів, конвертацій і взаєморозрахунків.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/cashboxes | отримати список кас |
| GET | /v1/cashboxes/:id | отримати одну касу |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID каси. |
title | Назва каси. |
code | Код каси. |
kind | Тип каси. |
filial_id | Філія або юридична особа. |
shared | Чи доступна каса спільно. |
active | Чи активна каса. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Способи оплати
Способи оплати допомагають повʼязати зовнішні способи оплати з внутрішніми касами або банківськими рахунками Skynum.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/payment_methods | отримати список способів оплати |
| GET | /v1/payment_methods/:id | отримати один спосіб оплати |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID способу оплати. |
title | Назва способу оплати. |
typepay | Тип оплати. |
cashbox_id | Каса, якщо спосіб оплати повʼязаний з готівкою. |
bankbox_id | Банківський рахунок, якщо спосіб оплати повʼязаний з безготівковою оплатою. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Статті витрат
Статті витрат використовуються у фінансових платежах і витратних операціях.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/expenses | отримати список статей витрат |
| GET | /v1/expenses/:id | отримати одну статтю витрат |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID статті витрат. |
title | Назва статті витрат. |
code | Код статті витрат. |
group_id | Група витрат. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Засновники
Засновники використовуються у фінансових операціях, коли компанія проводить розрахунки із засновниками.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/founders | отримати список засновників |
| GET | /v1/founders/:id | отримати одного засновника |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID засновника. |
title | Назва або імʼя засновника. |
code | Код. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Канали продажів
Канали продажів використовуються в документах, замовленнях, продажах, звітах та інтеграціях із сайтами або маркетплейсами.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/sale_channels | отримати список каналів продажів |
| GET | /v1/sale_channels/:id | отримати один канал продажів |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID каналу продажів. |
title | Назва каналу продажів. |
code | Код каналу продажів. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Податки
Податки використовуються для ПДВ, інших податкових операцій, зарплатних податків і фіскальних сценаріїв.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/taxes | отримати список податків |
| GET | /v1/taxes/:id | отримати один податок |
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID податку. |
code | Код податку. |
title | Назва податку. |
category | Категорія податку. |
rate | Ставка податку. |
tax_symbol | Податковий символ. |
excise_rate | Ставка акцизу. |
active | Чи активний податок. |
filial_id | Філія або юридична особа. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Локації
Локації використовуються для сегментації контрагентів за містом, регіоном або іншою зручною ознакою місцезнаходження.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/locations | отримати список локацій |
| GET | /v1/locations/:id | отримати одну локацію |
| POST | /v1/locations | створити локацію |
| PUT | /v1/locations/:id | оновити локацію |
Для створення й оновлення передається обʼєкт location.
{
"location": {
"title": "Київ"
}
}
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID локації. |
title | Назва локації. |
code | Код локації. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Одиниці виміру
Одиниці виміру використовуються в товарах, документах і звітах.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/measures | отримати список одиниць виміру |
| GET | /v1/measures/:id | отримати одну одиницю виміру |
| POST | /v1/measures | створити одиницю виміру |
| PUT | /v1/measures/:id | оновити одиницю виміру |
Для створення й оновлення передається обʼєкт measure.
{
"measure": {
"title": "шт"
}
}
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID одиниці виміру. |
title | Назва одиниці виміру. |
code | Код одиниці виміру. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Виробники
Виробники використовуються в картці товару, фільтрах і звітах.
Endpoint-и:
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/producers | отримати список виробників |
| GET | /v1/producers/:id | отримати одного виробника |
| POST | /v1/producers | створити виробника |
| PUT | /v1/producers/:id | оновити виробника |
Для створення й оновлення передається обʼєкт producer.
{
"producer": {
"title": "Skynum Brand"
}
}
Поля відповіді:
| Поле | Що означає |
|---|---|
id | ID виробника. |
title | Назва виробника. |
code | Код виробника. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Чеклист
Перед запуском інтеграції перевірте:
- які довідники потрібні для сценарію;
- чи має API-користувач доступ до потрібних філій, складів, кас і рахунків;
- чи зберігає інтеграція ID довідників, а не тільки назви;
- що робити, якщо довідник перейменували;
- як інтеграція реагує на неактивну касу, рахунок, склад або філію;
- чи потрібне створення локацій, одиниць виміру або виробників через API.
Повʼязані матеріали
- Структура платформи;
- Довідники;
- Статуси і стани;
- Філії та юридичні особи;
- Каси;
- Банківські рахунки;
- Валюти та курси валют через API;
- Склади через API.
Підсумок
Довідники через API — це основа для коректного запису документів, платежів і товарів. Перед write-запитами інтеграція має отримати актуальні ID довідників і використовувати їх у всіх повʼязаних ресурсах.