Контрагенти через API
API дозволяє читати, створювати, оновлювати й видаляти контрагентів.
Повʼязані інструкції:
- Покупці та постачальники;
- Створення контрагента;
- Картка контрагента;
- Групи контрагентів;
- Адреси контрагентів.
Endpoint-и
| Метод | Endpoint | Призначення |
|---|---|---|
| GET | /v1/contragents | отримати список контрагентів |
| POST | /v1/contragents | створити контрагента |
| GET | /v1/contragents/:id | отримати одного контрагента |
| PUT | /v1/contragents/:id | оновити контрагента |
| DELETE | /v1/contragents/:id | видалити контрагента |
Отримання списку контрагентів
GET /v1/contragents підтримує параметри:
| Параметр | Призначення |
|---|---|
offset | Сторінка або зміщення списку. |
limit | Кількість записів. |
query | Пошук за назвою, телефоном, номером дисконтної картки або email. |
group_id | Фільтр за групою контрагентів. |
location_id | Фільтр за локацією. |
archive | Показувати архівних контрагентів. |
status_id | Фільтр за статусом. |
with_custom_fields | Додати у відповідь додаткові поля. |
Перед створенням нового контрагента зовнішня система може спочатку шукати його за телефоном, email або дисконтною карткою. Це допомагає зменшити дублікати.
Отримання одного контрагента
GET /v1/contragents/:id повертає одного контрагента за внутрішнім ID Skynum.
Додатково можна передати with_custom_fields, щоб отримати додаткові поля контрагента.
Створення контрагента
Для створення контрагента обовʼязкове поле:
title.
Для запису API приймає:
| Поле | Призначення |
|---|---|
group_id | Група контрагента. |
code | Код контрагента. |
title | Назва або імʼя контрагента. |
status_id | Статус контрагента. |
instagram | Instagram. |
entity_type | Тип особи або компанії. |
location_id | Локація. |
phone | Телефон. |
email | Email. |
bank_id | Банк. |
bank_account | Банківський рахунок. |
taxnumber | Податковий номер. |
remark | Примітка. |
discount_card | Дисконтна картка. |
currency_id | Валюта контрагента. |
custom_fields | Додаткові поля. |
Поля у відповіді
| Поле | Що означає |
|---|---|
id | Внутрішній ID контрагента. |
group_id | ID групи контрагента. |
code | Код контрагента. |
title | Назва або імʼя контрагента. |
entity_type | Тип особи або компанії. |
status_id | ID статусу. |
instagram | Instagram. |
location_id | ID локації. |
phone | Телефон. |
email | Email. |
bank_id | ID банку. |
bank_account | Банківський рахунок. |
taxnumber | Податковий номер. |
remark | Примітка. |
discount_card | Дисконтна картка. |
group_title | Назва групи контрагента. |
location_title | Назва локації. |
status_title | Назва статусу. |
currency_code | Код валюти контрагента. |
bank_title | Назва банку. |
purchases_amount | Сума покупок контрагента. |
bonuses | Бонуси контрагента. |
addresses | Адреси контрагента. |
custom_fields | Додаткові поля, якщо передано with_custom_fields=true. |
created_at | Дата створення. |
updated_at | Дата оновлення. |
Групи, статуси й локації
Контрагент може бути привʼязаний до:
- групи через
group_id; - статусу через
status_id; - локації через
location_id.
Ці поля важливі, якщо в компанії контрагенти сегментуються для продажів, закупівель, SMS-розсилок, аналітики або прав доступу.
Адреси
У відповідях по контрагентах можуть повертатися адреси. Адреси потрібні для доставок і контактних даних.
Поточний API контрагентів повертає адреси у відповіді, але окремого endpoint-а для запису адрес контрагента в цьому ресурсі немає. Адресу доставки можна передавати в документі в блоці delivery.
Адреса може містити, зокрема:
kind;primary;address_line;street_name;house;flat;postal_code;notes;- глобальні або сервісні ID міста, відділення чи вулиці.
Для сценаріїв доставки також дивіться: Адреси доставки, Поля Нової пошти.
Додаткові поля
Для контрагентів підтримується custom_fields.
Щоб отримувати додаткові поля у відповіді списку або картки, використовуйте параметр:
with_custom_fields
Для власних довідників в API також доступні:
GET /v1/custom_termsGET /v1/custom_terms/:id
Докладніше: Додаткові поля.
Видалення контрагента
Endpoint DELETE /v1/contragents/:id видаляє контрагента через API.
Не використовуйте видалення як звичайний спосіб синхронізації. Якщо контрагент уже використовується в документах, платежах або взаєморозрахунках, видалення може бути небажаним для обліку.
Чеклист інтеграції
Перед синхронізацією контрагентів перевірте:
- яке поле є зовнішнім ключем інтеграції;
- як інтеграція шукає дублікати;
- чи потрібні групи контрагентів;
- чи потрібні статуси;
- чи передаються телефони й email в одному форматі;
- чи використовуються дисконтні картки;
- чи потрібні адреси доставки;
- чи потрібно читати або записувати додаткові поля.
Підсумок
API контрагентів дозволяє синхронізувати клієнтів, постачальників і контактні дані. Найважливіше для якісної інтеграції — правильно визначити зовнішній ключ, не створювати дублікати й не видаляти контрагентів без потреби.