Справочник методов API v5

Методов в API v5 несколько сотен, но все они укладываются в понятную структуру разделов и общих правил. Если понять логику именования, фильтров и пагинации, любой новый метод читается почти без документации — достаточно знать раздел и тип операции.

Разделы API и логика путей

Пути методов сгруппированы по предметным областям. Первый сегмент после версии указывает раздел, дальше идёт сущность и действие. Основные группы:

Внутри раздела действуют шаблоны: список — GET на корень раздела, создание — /create, редактирование — /{id}/edit, получение одного объекта — /{id}.

Метод /credentials как живой справочник

Самый полезный метод для разработчика — GET /api/v5/credentials. Он возвращает список методов, доступных текущему ключу, а также информацию о версиях сайта. Это позволяет:

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

Ответ содержит массив credentials со строками вида /api/orders, /api/orders/create. Сверяя нужные вам методы с этим списком, вы избегаете неожиданных 403 в бою.

Фильтры и выборки

Списочные методы принимают фильтры в формате filter[имя]=значение. Многие фильтры поддерживают массивы и диапазоны:

• Точное совпадение: filter[email]=user@example.com;
• Массив значений: filter[ids][]=1&filter[ids][]=2;
• Диапазон дат: filter[createdAtFrom]=2026-01-01 00:00:00 и createdAtTo;
• Статусы и группы: filter[extendedStatus][]=new.

Пример выборки новых заказов конкретного сайта:

GET /api/v5/orders?filter[extendedStatus][]=new&filter[sites][]=main&limit=100

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

Пагинация и обход больших выборок

Списки разбиваются на страницы параметрами limit (20, 50 или 100) и page. Ответ содержит блок навигации:

"pagination":{"limit":100,"totalCount":2450,"currentPage":1,"totalPageCount":25}

Чтобы выгрузить всю базу, обходят страницы, пока currentPage меньше totalPageCount. Для очень больших объёмов есть более устойчивый приём — итерация по filter[sinceId]: вы запрашиваете записи с id больше последнего полученного, что не страдает от смещения при параллельных изменениях данных.

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

Для массовых операций есть отдельные методы, экономящие запросы и лимиты:

• /orders/upload и /customers/upload — загрузка до 50 объектов за один вызов;
• /orders/statuses — быстрая проверка статусов группы заказов;
• /orders/fix-external-ids и /customers/fix-external-ids — привязка внешних идентификаторов к уже созданным записям;
• /orders/combine — объединение дублей заказов, /customers/combine — клиентов.

Пакетная загрузка возвращает массив uploadedOrders с соответствием внешних и внутренних id, а ошибки по отдельным объектам — в errors. Это ключевой инструмент первичной синхронизации, когда нужно перенести тысячи записей.

Параметры by и site

Два параметра встречаются почти во всех методах и часто становятся источником ошибок:

• by — по какому идентификатору искать сущность: id (внутренний id CRM) или externalId (ваш идентификатор на сайте). По умолчанию externalId.
• site — символьный код магазина, обязателен, когда externalId уникален только в пределах сайта.

Пример получения заказа по внутреннему id:

GET /api/v5/orders/8123?by=id

Если не указать by=id, система будет искать заказ с externalId, равным 8123, и вернёт 404. Эту деталь легко упустить при отладке.

Итог

Справочник методов v5 держится на нескольких повторяющихся принципах: разделы группируют сущности, действия выражаются суффиксами /create и /edit, выборки управляются filter[] и пагинацией, а by и site определяют адресацию объектов. Метод /credentials служит живой картой доступного вам API.

Мы разрабатываем интеграционные модули, которые аккуратно обходят эти методы: с корректной пагинацией через sinceId, пакетной загрузкой и обработкой частичных ошибок. Если нужен обмен, который не теряет и не дублирует данные при больших объёмах, поможем спроектировать и внедрить его.