Інтеграція з SalesDrive

Інтеграція поєднує CRM SalesDrive з обліковим контуром QUINCEFIN. Замовлення переходять із SalesDrive у QUINCEFIN, а товари, продажні ціни, собівартість і фактичні залишки можна передавати назад у SalesDrive без ручного дублювання.

Інтеграція доступна у конфігурації Національний стандарт (Україна).

Профіль знаходиться в меню Налаштування → Інтеграції → CRM-системи → SalesDrive.

Що підтримується

З SalesDrive у QUINCEFIN:

• ручний імпорт замовлень за вибраний період;
• автоматичний імпорт нових і змінених замовлень кожні 5 хвилин;
• отримання нових замовлень і змін статусу через webhook;
• створення документа Замовлення покупця;
• створення нового партнера, якщо покупця ще немає;
• створення нового товару, якщо товар не знайдено за артикулом;
• перенесення кількості, ціни, знижки, коментаря, статусу, способу оплати й доставки;
• перенесення адреси доставки та ТТН Нової пошти, якщо вони є в замовленні.

З QUINCEFIN у SalesDrive:

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

Обмін замовленнями односторонній: SalesDrive → QUINCEFIN. Зміни замовлення, зроблені в QUINCEFIN, назад у SalesDrive не надсилаються.

У якій послідовності налаштовувати

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

1. Підготуйте в QUINCEFIN користувача, власні організації, склади, папки та типи цін.
2. У SalesDrive створіть окремий API-ключ для QUINCEFIN.
3. У QUINCEFIN створіть профіль, введіть піддомен і API-ключ та натисніть Застосувати.
4. Після збереження натисніть Перевірити з’єднання.
5. Заповніть вкладку Замовлення і виконайте тестовий ручний імпорт.
6. Скопіюйте сформований у QUINCEFIN Webhook URL і додайте його у SalesDrive.
7. Заповніть вкладку Товари та спочатку виконайте Експортувати товари.
8. Після перевірки товарів виконайте Експортувати залишки.
9. Лише після успішного ручного тесту вмикайте Автоматичний імпорт.

Що підготувати перед створенням профілю

Перед експортом перевірте типи цін у QUINCEFIN: тип продажної ціни та тип собівартості повинні бути різними, а ціни товарів — чинними на поточну дату.

Створення API-ключа у SalesDrive

1. Увійдіть у SalesDrive з правами адміністратора.
2. Відкрийте Установки → Загальні налаштування і інтеграції → Інші сервіси → API.
3. Відкрийте API-ключі.
4. Виберіть створення API-ключа на рівні бази заявок, з якої QUINCEFIN має імпортувати замовлення.
5. Переконайтеся, що ключ має право читання заявок.
6. Створіть окремий ключ для інтеграції QUINCEFIN і скопіюйте його. Після цього не надсилайте ключ у відкритих чатах і не додавайте до інструкцій.

Пароль користувача SalesDrive не підходить для API. QUINCEFIN використовує саме API-ключ.

Важливо. Загальний API-ключ може успішно експортувати товари, отримувати статуси, способи оплати й доставки, але повертати 401 api key is invalid при читанні замовлень. Для імпорту замовлень використовуйте ключ на рівні бази заявок.

Офіційні матеріали SalesDrive: управління API-ключами та Swagger API.

Створення профілю в QUINCEFIN

Крок 1. Заповніть вкладку підключення

1. Відкрийте Налаштування → Інтеграції → CRM-системи → SalesDrive.
2. Натисніть Створити.
3. Заповніть поля:
   • Профіль — довільна зрозуміла назва, наприклад SalesDrive — основний магазин;
   • Акаунт (піддомен) — тільки частина адреси перед .salesdrive.me;
   • API-ключ — ключ, створений у SalesDrive.
4. Не вводьте в поле Акаунт https://, .salesdrive.me або шлях після домену.
5. Натисніть Застосувати. Це обов’язково: до першого збереження профіль ще не має ID, Webhook secret і Webhook URL.
6. Після збереження натисніть Перевірити з’єднання.

Приклад:

• адреса кабінету: https://myshop.salesdrive.me/;
• значення поля Акаунт (піддомен): myshop.

Крок 2. Перевірте автоматично сформовані поля

Після першого збереження QUINCEFIN заповнить:

• Webhook secret — внутрішній секрет профілю;
• Webhook URL — готову адресу, яку потрібно скопіювати в SalesDrive.

Ці поля не потрібно створювати вручну. Якщо ви змінюєте піддомен або API-ключ, спочатку натисніть Застосувати, а вже потім повторно перевіряйте з’єднання.

Налаштування імпорту замовлень

На вкладці Замовлення заповніть:

• Період — інтервал для ручного імпорту;
• Користувач — користувач QUINCEFIN, від імені якого створюються документи;
• Папка товарів — папка для нових товарів із замовлень SalesDrive;
• Папка партнерів — папка для нових покупців;
• Автоматичний імпорт — увімкніть тільки після успішного ручного тесту;
• Перекриття, хв — скільки хвилин попереднього періоду перевіряти повторно, щоб не пропустити зміни на межі синхронізації.

Як вибрати користувача

Вибирайте користувача, для якого в QUINCEFIN заповнені параметри за замовчуванням, потрібні для документа Замовлення покупця: організація, склад, сегмент діяльності, тип ціни та інші облікові реквізити вашого сценарію.

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

Як вибрати папки

• Папка товарів потрібна лише для позицій, яких ще немає в QUINCEFIN.
• Папка партнерів потрібна лише для нових покупців.
• Якщо папку не вибрати, новий запис створюється без окремої папки відповідно до правил профілю.

Рекомендоване перекриття — 5 хвилин. Допустиме значення — від 1 до 60 хвилин. Повторне отримання того самого замовлення не повинно створювати дубль: QUINCEFIN знаходить його за зовнішнім номером і оновлює непроведений документ.

Перший ручний імпорт

1. Виберіть невеликий період, у якому є одне відоме тестове замовлення.
2. Натисніть Застосувати.
3. Натисніть Імпорт.
4. Перевірте поле Останній обмін.
5. Відкрийте створений документ Замовлення покупця.
6. Перевірте покупця, товар, кількість, ціну, знижку, статус, спосіб оплати та доставку.
7. Лише після цього розширюйте період або вмикайте автоматичний імпорт.

Автоматичний імпорт

Після ввімкнення параметра Автоматичний імпорт QUINCEFIN перевіряє SalesDrive кожні 5 хвилин. Перший автоматичний запуск перевіряє останні 24 години, наступні — період від останньої успішної синхронізації з указаним перекриттям.

Налаштування webhook

Webhook скорочує затримку між створенням або зміною замовлення у SalesDrive та його появою в QUINCEFIN.

1. Збережіть профіль SalesDrive у QUINCEFIN.
2. Скопіюйте сформований Webhook URL.
3. У SalesDrive відкрийте Установки → Загальні налаштування і інтеграції → Інші сервіси → Webhook.
4. Створіть webhook і вставте URL із профілю QUINCEFIN.
5. Увімкніть події створення нового замовлення та зміни статусу.
6. Збережіть webhook.
7. Створіть тестове замовлення або змініть його статус.
8. Перевірте документ і поле Останній обмін у QUINCEFIN.

Після отримання webhook QUINCEFIN додатково запитує актуальні дані замовлення через SalesDrive API, а потім створює або оновлює документ.

Webhook URL містить секретний token. Не публікуйте його і не передавайте стороннім користувачам.

Докладніше: Webhook у SalesDrive.

Налаштування експорту товарів

На вкладці Товари поля заповнюються так:

Як вибрати організацію

У таблиці Залишки за організаціями та складами поле Організація визначає, залишки якої саме власної компанії QUINCEFIN будуть передані у SalesDrive. Під час розрахунку одночасно враховуються організація та склад із поточного рядка.

Не орієнтуйтеся лише на назву контрагента в документі надходження. У такому документі є дві різні сторони:

• Організація — ваша компанія, на баланс якої оприбутковано товар;
• Постачальник / контрагент — компанія, від якої надійшов товар.

Для перевірки відкрийте документ, яким сформовано залишок, і подивіться саме поле власної організації. У таблиці профілю SalesDrive потрібно вибрати цю саму організацію.

Якщо облік ведеться за кількома організаціями:

1. Використовуйте один профіль для одного кабінету SalesDrive.
2. У блоці Залишки за організаціями та складами додайте окремий рядок для кожної організації.
3. У кожному рядку виберіть Організацію та, за потреби, Склад QUINCEFIN.
4. Вкажіть окремий ID складу SalesDrive. Якщо рядків кілька, ID є обов’язковим і не повинен повторюватися.
5. Збережіть профіль кнопкою Застосувати. Кнопка Експортувати залишки обробить усі рядки за один запуск: для кожного рядка залишки буде передано до відповідного складу SalesDrive.

Спочатку виберіть режим складів

Перед першим експортом залишків виберіть один із двох режимів.

Один загальний склад у SalesDrive

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

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

Декілька складів у SalesDrive

Вибирайте цей режим, якщо залишки кожного складу QUINCEFIN мають потрапляти до окремого складу SalesDrive.

• додайте в таблицю рядок для кожної пари «організація/склад QUINCEFIN → склад SalesDrive»;
• у кожному рядку виберіть конкретну організацію, потрібний склад QUINCEFIN і точний ID складу SalesDrive;
• усі ID складів SalesDrive у таблиці мають бути заповнені та не повинні повторюватися;
• окремі профілі для цих відповідностей створювати не потрібно.

Критично: після першого експорту залишків не змінюйте режим із одного загального складу на декілька складів або навпаки. У SalesDrive залишок, переданий як загальний, і залишки окремих складів можуть враховуватися разом. Після такого перемикання кількість стане некоректною та перестане збігатися із QUINCEFIN. Якщо потрібна інша схема складів, узгодьте очищення або перенесення залишків у SalesDrive з відповідальним за облік до нового експорту.

Де взяти ID складу SalesDrive

1. У SalesDrive відкрийте Установки → Загальні налаштування і інтеграції → Інші сервіси → API.
2. Знайдіть ID складу, який має оновлювати QUINCEFIN, або отримайте його в адміністратора чи підтримки SalesDrive.
3. Скопіюйте точний ID без заміни на назву складу чи ID складу QUINCEFIN.

Не копіюйте сюди ID складу з QUINCEFIN — це різні довідники. Для режиму одного загального складу залиште один рядок і не заповнюйте в ньому Склад та ID складу SalesDrive.

Офіційно SalesDrive підтримує роботу з кількома складами та імпорт залишків через API: облік складу в SalesDrive.

Як підготувати типи цін

1. У QUINCEFIN відкрийте довідник Типи цін.
2. Переконайтеся, що є окремий тип для продажу, наприклад Роздрібна, і окремий тип для собівартості, наприклад Закупівельна.
3. У картках товарів перевірте актуальні ціни обох типів на поточну дату.
4. У профілі SalesDrive виберіть їх у відповідних полях — не навпаки.

Важливо:

• товар без актуальної продажної ціни не потрапляє до повного експорту товарів;
• якщо для товару немає актуальної собівартості, поле собівартості в SalesDrive не перезаписується нулем;
• кнопка Експортувати залишки не переносить продажну ціну або собівартість — для цього використовуйте Експортувати товари.

Як вибрати групи товарів

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

Перед першим експортом перевірте:

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

Перший експорт товарів

1. Виберіть обидва типи цін і, за потреби, групи товарів.
2. Натисніть Застосувати.
3. Натисніть Експортувати товари.
4. Відкрийте в SalesDrive Товари/Послуги.
5. На кількох тестових товарах перевірте назву, артикул, колонку Ціна та колонку Собівартість.
6. Якщо результат правильний, виконайте експорт для всього потрібного каталогу. Ця кнопка передає лише картки товарів — без залишків за організаціями та складами — тому одна картка не дублюється через кілька відповідностей складів.

Експорт залишків

Кнопка Експортувати залишки оновлює тільки кількість. Для виконання вимог SalesDrive QUINCEFIN також технічно передає назву товару, але додає її до переліку полів, які не потрібно оновлювати. Тому наявні назви, описи, продажні ціни та собівартість у SalesDrive не змінюються.

Рекомендована послідовність:

1. перевірте, що в кожному рядку профілю вибрано ту саму організацію та склад, на які опубліковано складські документи;
2. натисніть Застосувати;
3. один раз виконайте Експортувати товари;
4. перевірте картки товарів у SalesDrive;
5. надалі для оперативного оновлення кількості використовуйте Експортувати залишки: усі рядки відповідностей профілю буде оброблено, незалежно від їхнього порядку.

Після успішного запуску поле Останній обмін має оновитися. Кількість у SalesDrive повинна відповідати залишку вибраної організації на вибраному складі QUINCEFIN.

Як зіставляються дані

• замовлення — за зовнішнім номером, сформованим із форми та ID SalesDrive;
• товари під час імпорту — насамперед за артикулом SalesDrive;
• партнери — за назвою покупця;
• статуси — за назвами статусів SalesDrive;
• товари під час експорту — за стабільним внутрішнім кодом QUINCEFIN, артикулом або ID картки.

Якщо статусу замовлення ще немає в QUINCEFIN, система створює відповідну стадію документа Замовлення покупця.

Типові проблеми

Безпека

• не використовуйте пароль кабінету замість API-ключа;
• не надсилайте API-ключ і Webhook URL у відкритих чатах;
• створюйте окремий ключ для інтеграції QUINCEFIN;
• після зміни API-ключа оновіть профіль, натисніть Застосувати і повторно перевірте з’єднання;
• якщо ключ став відомий стороннім, відкличте його у SalesDrive і створіть новий.

Пов’язана документація

• Інтеграції від QUINCEFIN
• Документ «Замовлення»
• Типи цін