Техническое задание

1. Цель и общая схема интеграции

Цель: Автоматическая передача заказов (сделок) из amoCRM в систему BaseLinker для дальнейшей обработки, логистики и хранения информации о заказах.
Схема: При создании/изменении сделки в amoCRM (например, при переходе на нужную стадию воронки) данные по заказу отправляются в BaseLinker через API BaseLinker. В результате в BaseLinker формируется новый заказ или обновляется существующий.

2. Область применения

• amoCRM выступает в роли CRM, где менеджеры обрабатывают и ведут сделки.
• BaseLinker — система, через которую идёт работа с фулфилмент-партнёром, логистика и учёт статусов отгрузки и доставки.

3. Источник данных (amoCRM)

1. amoCRM

   • Необходимо настроить (или использовать уже имеющиеся) вебхуки / ботов / сервис-соединение, чтобы при достижении определённых условий (например, «Сделка перешла на стадию Заказ подтверждён») автоматически вызывалась интеграция, которая отправляет данные в BaseLinker.
   • Можно также организовать отправку при создании сделки, при изменении полей сделки, при закрытии сделки и т.д. — в зависимости от бизнес-логики.

2. Данные, которые передаются из amoCRM:

   • Номер сделки / ID
   • Дата создания сделки (или дата конвертации в заказ)
   • Клиент (контакт):
     • Имя
     • Телефон
     • E-mail (если есть)
     • Адрес (если есть в полях сделки/контакта)
   • Товары (продукты в сделке):
     • Название товара
     • Количество
     • Цена (за единицу)
   • Сумма сделки
   • Комментарий (примечание менеджера / комментарий покупателя)
   • Способ оплаты (при наличии, например, наложенный платёж, предоплата, оплата картой и т.д.)
   • Способ доставки или дополнительные поля (город, отделение почты и т. п.), если эти данные хранятся в amoCRM.

(Список может быть расширен исходя из того, какие поля реально есть и нужны в BaseLinker.)

4. Приёмник данных (BaseLinker)

1. BaseLinker

   • Данные передаются через метод addOrder (либо другой соответствующий метод, см. документацию).
   • При передаче создаётся новый заказ в BaseLinker.
   • Опционально можно добавлять информацию об источнике («amoCRM deal #...») в поля комментария к заказу, чтобы менеджеры видели, откуда пришла информация.

2. Требования к формированию запроса:

   • Метод: POST (или GET, согласно документации, но обычно POST)
   • Адрес: https://api.baselinker.com/connector.php (или иной, в зависимости от инструкции)
   • Параметры:
     • token (токен API BaseLinker, выданный в ЛК)
     • method=addOrder
     • Остальные параметры согласно документации addOrder (например, order_status_id, shipping_fullname, products[], и т.д.).
   • Если нужно, чтобы заказ попадал в определённый статус или определённый магазин внутри BaseLinker, указываем order_status_id, shop_id и т.п.

3. Пример структуры данных для addOrder (с учётом того, что часть полей будет подставляться из amoCRM):

   jsonКопироватьРедактировать{
     "method": "addOrder",
     "parameters": {
       "order_status_id": 1234,
       "date_add": 1678345200,              // UNIX timestamp, дата создания
       "phone": "******",
       "email": "****",
       "user_comments": "Комментарий из amoCRM",
       "admin_comments": "Сделка #123, менеджер: Иванов",
       "delivery_method": "Курьер",
       "payment_method": "Карта",
       "products": [
         {
           "storage": "catalog",
           "product_id": 100500,
           "name": "Название товара",
           "quantity": 2,
           "price_brutto": 199.99
         },
         {
           "storage": "manual",
           "name": "Еще один товар",
           "quantity": 1,
           "price_brutto": 99.90
         }
       ]
     }
   }
   

   (Это только пример — конечный формат зависит от того, как именно вы храните товары.)

5. Логика интеграции (шаги)

1. Отслеживание события в amoCRM

   • Использовать встроенный функционал вебхуков/робота/сценария — при выполнении условия (например, «Сделка → Стадия: Оформлен заказ»).
   • Как только сделка достигает данной стадии, amoCRM отправляет (через webhook или сервисный аккаунт) данные сделки на ваш сервер/скрипт (или напрямую в BaseLinker, но обычно рекомендуется иметь промежуточный скрипт).

2. Обработка данных (промежуточный слой или сервис-коннектор)

   • Получаем структуру данных из amoCRM (JSON с информацией о сделке, контакте, товарах).
   • Преобразуем в формат, который ожидает BaseLinker API (addOrder).
   • Вставляем обязательные поля (token, method и т.д.).

3. Отправка в BaseLinker

   • Выполняем POST-запрос на URL API BaseLinker.
   • Обрабатываем ответ (проверяем, что status = «SUCCESS»).
   • Логируем результат (успех/ошибка).

4. Обработка ошибок

   • Если BaseLinker вернул ошибку (например, неверный токен, недостаточно данных, неверный формат), необходимо:
     • Логировать ошибку.
     • (Опционально) уведомлять ответственного менеджера/разработчика или записывать комментарий в amoCRM.

5. Дополнительная логика (по желанию):

   • Обновление статуса сделки в amoCRM при успешном добавлении в BaseLinker.
   • Двусторонняя интеграция (например, при смене статуса в BaseLinker – обновлять стадию в amoCRM). Для этого потребуется настраивать вебхуки со стороны BaseLinker + API amoCRM.
   • Передача трек-номера (если логистика формируется в BaseLinker, а трек нужно отобразить в amoCRM).

6. Технические детали

1. Способ реализации:

   • Можно написать собственный скрипт на PHP/Python/Node.js, размещённый на вашем сервере, который принимает вебхук от amoCRM и отправляет заказ в BaseLinker.
   • Либо использовать готовые сервисы-коннекторы (Make, Albato, ApiX-Drive и т.п.), если это подходит по бюджету и функционалу.

2. Авторизация:

   • amoCRM: потребуется создать интеграцию (OAuth) или использовать вебхук, который генерируется в разделе «Интеграции».
   • BaseLinker: нужен API token (сгенерировать в личном кабинете BaseLinker).

3. Хранение ключей:

   • Токен amoCRM и API token BaseLinker необходимо хранить в конфигурационных файлах на сервере, с ограниченным доступом.

4. Логирование:

   • Создать логи запросов и ответов (минимум: статус ответа, тело запроса, время отправки).
   • При возникновении ошибок — сохранять информацию об ошибках.

5. Тестирование:

   • Создать тестовую сделку в amoCRM, выполнить все триггеры. Проверить, что заказ корректно появился в BaseLinker.
   • Проверить корректность отображения товаров, цен, контактов, статусов и полей комментария.

7. Сроки и результаты

1. Сроки разработки: определить конкретно (например, 5-7 рабочих дней).
2. Результат:
   • Рабочий скрипт/интеграция, которая корректно передаёт заказы из amoCRM в BaseLinker по описанному событию (изменение стадии).
   • Документация по настройке и запуску (чтобы в будущем можно было модифицировать).
   • Инструкции для менеджеров, как использовать (на какую стадию переводить сделку, какие данные обязательны для ввода и т.д.).

8. Контроль выполнения и приёмка

1. Тестирование:
   • Будут выполнены тестовые сделки в amoCRM с разными наборами данных.
   • Проверяется, что в BaseLinker создаются заказы с корректными полями.
2. Фиксация ошибок:
   • Все найденные баги описываются, разработчик исправляет их до окончательной приёмки.
3. Окончательное утверждение:
   • После успешного теста и подтверждения функционала — интеграция считается внедрённой.

Примечания

• Если в будущем потребуется обратная синхронизация (например, когда заказ меняет статус в BaseLinker, а в amoCRM нужно автоматически менять стадию сделки), то нужно будет добавить аналогичные вызовы (webhook из BaseLinker → API amoCRM).
• В рамках данного ТЗ основная задача — однонаправленно передавать заказы из amoCRM в BaseLinker.
• Настраивайте соответствие полей amoCRM и BaseLinker заранее, чтобы избежать несоответствий (например, чтобы не потерять адрес доставки или телефон клиента).