Работа с клиентами через API

Клиент в RetailCRM связывает заказы, коммуникации и историю покупок, поэтому чистота базы напрямую влияет на аналитику и лояльность. API даёт создавать, искать, обновлять и объединять клиентов, а также работать с корпоративными клиентами и произвольными полями.

Объект customer и его создание

Клиент создаётся методом POST /api/v5/customers/create. Тело — параметр customer с JSON и site:

customer={"externalId":"u-501","firstName":"Ольга","phones":[{"number":"+79005556677"}],"email":"olga@example.com"}

Базовые поля — имя, телефоны (массив phones), email, пол, дата рождения. Контактные данные лучше нормализовать до отправки: телефоны в едином формате упрощают дальнейший поиск дублей. В ответе приходит внутренний id, который стоит сохранить рядом с вашим externalId.

Поиск и чтение клиентов

Список клиентов возвращает GET /api/v5/customers с фильтрами. Наиболее востребованные:

• filter[email] — по адресу почты;
• filter[name] — по имени/фамилии;
• filter[phone] — по номеру телефона;
• filter[externalIds][] — по вашим идентификаторам;
• filter[dateFrom] / filter[dateTo] — по дате регистрации.

Одиночный клиент читается через GET /api/v5/customers/{id} с параметром by. Перед созданием нового клиента полезно выполнить поиск по телефону и email — это первый барьер против дублей.

Дедупликация и объединение

Дубли неизбежны при нескольких источниках данных: сайт, колл-центр, маркетплейсы. RetailCRM предлагает инструменты для их устранения через API.

Метод /customers/combine принимает список объединяемых клиентов и целевого клиента, в которого переносятся заказы и история. Операция необратима, поэтому в интеграции её стоит выполнять по чётким правилам совпадения.

Корпоративные клиенты

Для B2B в RetailCRM есть отдельная сущность — корпоративный клиент, со своим разделом /customers-corporate. Её модель богаче обычного клиента:

• Компания — юрлицо с реквизитами;
• Контакты — сотрудники, привязанные к компании;
• Адреса — несколько адресов доставки и юридических адресов.

Заказ корпоративного клиента ссылается и на компанию, и на конкретное контактное лицо. При интеграции B2B-портала это позволяет корректно разделять, кто разместил заказ и от имени какого юрлица. Методы аналогичны обычным клиентам: /customers-corporate/create, /customers-corporate/{id}/edit и вложенные методы для компаний и контактов.

Пользовательские поля и сегменты

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

customer={"customFields":{"loyalty_level":"gold","consent":true}}

Список доступных полей отдаёт справочник /custom-fields. Сегменты клиентов (динамические группы по правилам) читаются через /segments и удобны для выгрузок в рассылки и рекламные системы. Через API вы получаете принадлежность клиента к сегментам, но сами правила настраиваются в CRM.

Стратегия синхронизации базы

Устойчивая синхронизация клиентов опирается на несколько правил:

1. Единый ключ — externalId вашей системы, сохранённый в CRM.
2. Нормализация телефонов и email до отправки, чтобы поиск дублей был точным.
3. Инкрементальная выгрузка изменений по дате и sinceId, а не полный проход при каждой сессии.
4. Пакетная загрузка первичного импорта через /customers/upload партиями до 50 записей.

Такой подход снижает нагрузку на лимиты API и держит базу консистентной даже при нескольких источниках данных.

Итог

Управление клиентами через API — это создание и правка объекта customer, точечный поиск по контактам, дедупликация через /customers/combine, отдельная модель для B2B в /customers-corporate и произвольные данные в customFields. Чистота базы зависит от дисциплины с externalId и нормализацией контактов.

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