Документація API

Дана документація описує параметри та методи роботи з API SaleApp.

Ключ доступу до API

Підтримується два варіанта доступу до API: 

• По ключу організації
• По ключу контрагента (лише робота з замовленнями)

Для початку роботи з API необхідно провести генерування ключа доступу до API у розділі "Налаштування" - "Безпека", особистого кабінету, для створення ключа організації. Або провести генерування ключа API контрагента у налаштуваннях потрібного контрагента для подальшого його роботи з замовленнями по API.

Всі параметри запитів повинні відправлятися методом POST.

https://saleapp.com.ua/server/api/[Метод API]?secret_key=[Ключ API]

Всі методи підтримують наступні типи запитів (method_type):

GET - отримання даних

POST - створення запису

PUT- оновлення запису

DELETE- видалення запису

Партнерське API захищене від зловживань по IP-адресі клієнта.

• IP-адреса визначається у порядку: HTTP_CLIENT_IP → HTTP_X_FORWARDED_FOR → REMOTE_ADDR.
• Кожен запит логується. Записи старші за 5 хвилин видаляються автоматично при кожному наступному виклику.
• Якщо з одного IP надійшло понад 100 запитів за останню хвилину — IP блокується перманентно. Автоматичного розблокування немає, зняти блок може лише адміністратор SaleApp.
• Перевірка на блокування відбувається до перевірки ключа доступу — заблокований IP отримує розрив з’єднання без відповіді у форматі помилки.

Рекомендація: не перевищуйте 100 запитів на хвилину з одного джерела. Для масового обміну даними використовуйте параметр page для пакетного отримання записів замість запиту по одному.

Партнерське API повертає JSON. Формат помилок навмисно відрізняється від внутрішнього API системи — він зафіксований у контракті з партнерами і не змінюється.

• HTTP-статус відповіді завжди 200, навіть у разі помилки — помилка не сигналізується кодом відповіді.
• error — рядок "true" або "false" (не булеве значення JSON).
• error_description — текст помилки українською мовою (саме це поле, а не error_text, який використовується в решті системи).

{
  "error": "true",
  "error_description": "Невірний ключ доступу"
}

Успішна відповідь має "error": "false" та додаткові поля з результатом — об’єктом одного запису (пошук по id/external_id) або масивом записів (посторінковий вивід через page).

Довідник тегів контрагентів (таблиця clients_type). Доступ — лише за ключем організації (secret_key, видається у розділі «Налаштування» → «Безпека»).

Поля запису:

• id (number) — внутрішній ідентифікатор SaleApp
• external_id (number) — зовнішній ідентифікатор, переданий партнером при створенні запису
• page (number) — номер сторінки для посторінкового виводу (20 записів на сторінку)
• name (string) — назва тегу
• color (string) — колір тегу

Підтримуються операції отримання, створення, оновлення та видалення — див. дочірні розділи нижче.

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Якщо вказано параметр page більше нуля — параметри id та external_id ігноруються, результат: масив усіх записів вказаної сторінки (по 20 записів). Якщо page не вказано або дорівнює нулю — пошук іде по id та external_id (пріоритет у id), результат — об’єкт одного запису.

curl -X POST "https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=GET" \
  -d "page=1"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Параметри тіла: external_id, name, color.

curl -X POST "https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=POST" \
  -d "external_id=101" \
  -d "name=VIP" \
  -d "color=#ff0000"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Для ідентифікації запису передайте id або external_id. Оновлювані поля: name, color.

curl -X POST "https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=PUT" \
  -d "external_id=101" \
  -d "name=VIP-2"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Для ідентифікації запису передайте id або external_id.

curl -X POST "https://saleapp.com.ua/server/api/CounterpartyTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=DELETE" \
  -d "external_id=101"

Довідник контрагентів (таблиця clients) — клієнти, постачальники, ліди. Доступ — лише за ключем організації.

Поля запису:

• id (number) — внутрішній ідентифікатор SaleApp
• external_id (number) — зовнішній ідентифікатор
• page (number) — номер сторінки посторінкового виводу
• phone (string) — телефон
• mail (string) — email
• lid (number, 0/1) — ознака ліда (ще не підтверджений клієнт)
• name (string) — назва/ПІБ
• addres (string) — адреса
• type (number) — тип контрагента

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Окрім пошуку по id/external_id/page, GET додатково підтримує точний пошук за phone, mail або lid.

curl -X POST "https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=GET" \
  -d "phone=+380501234567"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Параметри тіла: external_id, phone, mail, lid, name, addres, type.

curl -X POST "https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=POST" \
  -d "external_id=555" \
  -d "name=Іван Петренко" \
  -d "phone=+380501234567" \
  -d "type=1"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Для ідентифікації запису передайте id або external_id.

curl -X POST "https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=PUT" \
  -d "external_id=555" \
  -d "phone=+380509876543"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Для ідентифікації запису передайте id або external_id.

curl -X POST "https://saleapp.com.ua/server/api/Counterparty?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=DELETE" \
  -d "external_id=555"

Довідник товарів (таблиця products). Доступ — лише за ключем організації.

Поля запису:

• id (number) — внутрішній ідентифікатор SaleApp
• external_id (number) — зовнішній ідентифікатор
• page (number) — номер сторінки посторінкового виводу
• sku (string) — артикул
• name (string) — назва товару
• cost (number) — ціна
• max_discount (number) — максимальна знижка, %
• markdown (number) — уцінка
• promo_percent (number) — розмір знижки акції, %
• promo_end_date (date) — дата завершення акції

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

curl -X POST "https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=GET" \
  -d "page=1"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Параметри тіла: external_id, sku, name, cost, max_discount, markdown, promo_percent, promo_end_date.

curl -X POST "https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=POST" \
  -d "external_id=9001" \
  -d "sku=SKU-001" \
  -d "name=Товар 1" \
  -d "cost=499.90"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Для ідентифікації запису передайте id або external_id.

curl -X POST "https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=PUT" \
  -d "external_id=9001" \
  -d "cost=549.90"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Для ідентифікації запису передайте id або external_id.

curl -X POST "https://saleapp.com.ua/server/api/Nomenclature?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=DELETE" \
  -d "external_id=9001"

Довідник тегів замовлень (таблиця orders_type). Доступ — лише за ключем організації.

Поля запису: id, external_id, page, name, color — аналогічно до тегів контрагентів.

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

curl -X POST "https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=GET" \
  -d "page=1"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

curl -X POST "https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=POST" \
  -d "external_id=201" \
  -d "name=Термінове" \
  -d "color=#ffcc00"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

curl -X POST "https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=PUT" \
  -d "external_id=201" \
  -d "name=Дуже термінове"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

curl -X POST "https://saleapp.com.ua/server/api/OrdersTags?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=DELETE" \
  -d "external_id=201"

Найскладніший ендпоінт партнерського API (таблиці orders/orders_line).

Авторизація — два варіанти:

• Ключ організації — повний доступ до замовлень організації.
• Ключ клієнта (clients.client_key) — доступ обмежений замовленнями, повʼязаними саме з цим контрагентом-постачальником; валюта й склад визначаються автоматично з налаштувань контрагента (api_curency_id, api_warehouse), курс валюти береться на поточну дату.

Ендпоінт спершу пробує ключ організації, і лише якщо його не знайдено — ключ клієнта.

Поля запису: id, number, external_id, client_id, curency_id, warehouse_id, type, delivery_types, city_ref, city, branch_ref, addres, receiver_name, receiver_phone, insurance_amount, delivery_amount, products (JSON-масив позицій), funnel, custom_fields (JSON).

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Пошук — за id, number або external_id. Відповідь збагачується додатковими полями: розшифрована назва типу замовлення, розпакований custom_fields, назва воронки, позиції замовлення (join із товарами). Якщо авторизація проведена ключем клієнта — для кожної позиції додатково повертається код постачальника (products_codes), обмежений саме цим клієнтом.

curl -X POST "https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=GET" \
  -d "number=SO-000123"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

При створенні:

• Місто та відділення Нової Пошти резолвляться за переданими city/city_ref/branch_ref.
• Товарні позиції в products зіставляються за id, sku, external_id або кодом постачальника (для ключа клієнта).
• Залишки на складі резервуються автоматично, якщо це не заборонено налаштуваннями воронки замовлення.
• insurance_amount (сума страхування), якщо задана, примусово підіймається до мінімум 300.
• receiver_phone очищується від усіх символів, окрім цифр, крапки та коми, перед збереженням.

curl -X POST "https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=POST" \
  -d "external_id=EXT-777" \
  -d "receiver_name=Іван Петренко" \
  -d "receiver_phone=+380501234567" \
  -d "city=Київ" \
  -d "products[0][sku]=SKU-001" \
  -d "products[0][qty]=2"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Оновлення дозволене лише поки статус замовлення дорівнює 0, 1 або 2 (Новий / Повністю зарезервований / Частково зарезервований). Замовлення, що вже просунулось далі по конвеєру (на збиранні, упаковане, відвантажене), через це API незмінне — запит поверне помилку.

curl -X POST "https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=PUT" \
  -d "external_id=EXT-777" \
  -d "receiver_phone=+380509876543"

Транспорт: усі запити виконуються фізично як HTTP POST на адресу https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ, тіло — application/x-www-form-urlencoded. Конкретна дія визначається полем method_type у тілі запиту (імітація REST-методів, а не реальний HTTP-метод) — тому фізично цей запит теж POST.

Видалення дозволене лише поки статус замовлення дорівнює 0, 1 або 2 — так само, як і для оновлення.

curl -X POST "https://saleapp.com.ua/server/api/Orders?secret_key=ВАШ_КЛЮЧ" \
  -d "method_type=DELETE" \
  -d "external_id=EXT-777"