RetailCRM API v5: обзор и авторизация

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

Что представляет собой API v5

RetailCRM предоставляет HTTP REST API, работающий поверх адреса вашего аккаунта. Базовый URL строится по шаблону https://{account}.retailcrm.ru/api/v5/, где {account} — поддомен вашей системы. Для аккаунтов на собственном домене (box-версия) адрес будет вида https://crm.example.com/api/v5/.

Версия v5 — актуальная и рекомендуемая. Более ранние v3 и v4 поддерживаются для совместимости, но новые методы и поля появляются только в пятой версии, поэтому все новые интеграции стоит строить сразу на ней.

• Транспорт: только HTTPS, обычный HTTP отклоняется.
• Методы HTTP: GET для чтения, POST для создания и изменения данных.
• Формат ответа: всегда JSON, даже для ошибок.
• Кодировка: UTF-8.

Ключ доступа apiKey и как его передавать

Авторизация построена на ключах доступа (apiKey). Ключ создаётся в интерфейсе CRM в разделе Настройки → Интеграция → Ключи доступа к API. Каждый ключ привязан к набору прав и, при необходимости, к конкретным магазинам (сайтам).

Передать ключ можно двумя способами:

• Заголовком X-API-KEY: {apiKey} — предпочтительный вариант, ключ не попадает в логи как query-параметр;
• Параметром запроса apiKey={apiKey} — работает и в GET, и в POST.

Пример первого запроса — проверка учётных данных:

curl 'https://demo.retailcrm.ru/api/v5/api-versions' -H 'X-API-KEY: aBcD1234...'

Метод /api-versions и /credentials удобны для стартовой диагностики: первый возвращает список поддерживаемых версий, второй — перечень методов, доступных данному ключу.

Права доступа и области видимости

При создании ключа вы отмечаете, какие группы методов ему разрешены. Права гранулированы по разделам: заказы, клиенты, справочники, склад, аналитика и так далее. Если ключ вызовет метод вне своего набора прав, API вернёт HTTP 403 с сообщением об отсутствии доступа.

Отдельно ключ можно ограничить магазинами: если в системе несколько сайтов, ключ увидит только назначенные ему. Это удобно для мультибрендовых проектов и для того, чтобы подрядчик не получил доступ ко всем данным сразу.

Формат запросов и ответов

Запросы на изменение отправляются как application/x-www-form-urlencoded. Сложные объекты передаются в виде JSON-строки в отдельном параметре. Например, при создании заказа тело содержит параметр order с сериализованным JSON:

curl -X POST 'https://demo.retailcrm.ru/api/v5/orders/create' -H 'X-API-KEY: ...' --data-urlencode 'order={"firstName":"Иван","phone":"+79000000000"}' --data 'site=main'

Ответ всегда содержит булево поле success. При удачном создании возвращается идентификатор сущности:

{"success":true,"id":8123,"order":{...}}

• Чтение использует GET с фильтрами вида filter[email]=user@example.com и постраничной навигацией limit / page.
• Списочные методы возвращают объект pagination с полями totalCount, currentPage, totalPageCount.

Коды ответов и разбор ошибок

RetailCRM использует стандартные HTTP-статусы плюс структурированное тело ошибки. При неуспехе success равно false, а детали лежат в полях errorMsg и errors.

Пример тела ошибки валидации:

{"success":false,"errorMsg":"Errors in the entity format","errors":{"phone":"Телефон некорректен"}}

SDK и первые шаги на практике

Официальные клиенты снимают рутину сериализации и подписи. Для PHP есть retailcrm/api-client-php, для других языков — сообщество и REST напрямую. Клиент инкапсулирует базовый URL, ключ и версию:

1. Установите SDK: composer require retailcrm/api-client-php.
2. Инициализируйте клиент с адресом аккаунта и apiKey.
3. Вызывайте методы вроде $client->request->ordersCreate($order).

Если пишете на другом стеке, достаточно любого HTTP-клиента: важно лишь корректно URL-кодировать JSON-объекты и добавлять заголовок с ключом. Рекомендованный порядок освоения: /credentials → чтение справочников /reference/sites → чтение заказов /orders → создание тестового заказа в отдельном магазине.

Итог

API v5 RetailCRM — это HTTPS REST с авторизацией по apiKey, JSON-ответами и form-urlencoded запросами, где сложные объекты передаются JSON-строкой. Ключевые опоры на старте: правильно выданный ключ с нужными правами, разбор поля success вместо слепой веры в HTTP-код и аккуратная работа с фильтрами и пагинацией.

Мы проектируем и внедряем интеграции RetailCRM с сайтами на 1С-Битрикс и учётными системами: настраиваем безопасное хранение ключей, разграничение прав и отказоустойчивый обмен. Если нужна надёжная связка CRM и вашего проекта — поможем спроектировать её так, чтобы она пережила рост данных и нагрузки.