RetailCRM

Приложение RetailCRM подключает API v5 магазина к рабочему столу Promto. Агент может работать с заказами, покупателями, товарами, статусами, задачами и файлами в пределах прав выданного ключа.

Назначение

Используйте RetailCRM для сводок по заказам, контроля статусов, анализа новых покупателей, поиска задач и подготовки точечных исправлений в карточках.

Подключение

1. Создайте API-ключ v5 в RetailCRM.
2. Разрешите только необходимые методы и выберите магазины, доступные интеграции.
3. В приложении укажите адрес аккаунта и API-ключ.
4. Нажмите Проверить и подключить.

Promto проверяет ключ через /api/credentials. Поддерживаются аккаунты в доменах retailcrm.ru, retailcrm.pro и simla.com. Ключ сохраняется на сервере и больше не показывается в браузере.

Интерфейс и данные

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

Выбор магазинов и права методов задаются в RetailCRM. Promto не расширяет их и не объединяет недоступные магазины в общий список.

Возможности агента

Инструмент — promto_retailcrm. После capabilities доступны, в частности:

• /orders — заказы;
• /customers — покупатели;
• /store/products — товары;
• /tasks — задачи;
• /reference/statuses — справочник статусов;
• /orders/{externalId}/edit — изменение заказа после подтверждения;
• /files/upload — загрузка небольшого файла после подтверждения.

API v5 принимает записывающие поля как форму. Вложенные объекты order, customer или task агент передаёт в params.body, а сервер сериализует их в формат RetailCRM.

Сценарии

Заказы в работе

Через promto_retailcrm сначала вызови capabilities, затем прочитай заказы за нужный период. Сгруппируй по статусам и магазинам, отдельно покажи просроченные задачи. Ничего не меняй.

Новые покупатели

Через promto_retailcrm покажи новых покупателей и их последние заказы. Запрашивай только нужные поля и страницы.

Ограничения и подтверждения

• Любая запись в заказ, покупателя, задачу или справочник требует явного согласия и confirm=true.
• Доступность методов зависит от прав API-ключа и выбранных магазинов.
• Обычные записи отправляются как form-поля, а не как произвольный JSON-запрос.
• Для /files/upload передаётся только body.content_base64; сервер декодирует его и отправляет бинарное содержимое.
• Размер загружаемого файла ограничен 512 КБ. Общий ответ прокси также ограничен 512 КБ.

Если что-то не работает

• Ключ не проходит проверку. Проверьте, что это ключ API v5 и ему разрешён служебный метод проверки.
• 403 на одном разделе. Добавьте нужное право ключу и проверьте список разрешённых магазинов.
• Заказ не найден. Уточните, используется внутренний ID или externalId, и в каком магазине находится заказ.
• Ошибка тела записи. Передавайте объект с полями официальной формы; не отправляйте строку или массив вместо объекта.
• Файл отклонён. Проверьте строгий Base64 без пробелов и размер исходного файла не более 512 КБ.

Связанные материалы

• Интеграции
• Агенты
• Настройки Promto