SelSup Developers

Основы интеграции · Руководства

Начало работы

Авторизация, первый запрос, локализованные ошибки, пагинация и безопасный выход интеграции в production.

4 разделовПрактическое руководство
→

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

Backend-разработчики и интеграторы

01

Авторизация и хранение токена

API-токен передаётся без префикса Bearer в заголовке Authorization.

Создавайте отдельный токен для каждой интеграции. Так его можно отозвать без остановки остальных подключений и выдать только необходимые права.

Храните токен в секретах серверного приложения. Не помещайте его в браузерный JavaScript, мобильное приложение, URL, логи или систему аналитики.

!
Заголовок отличается от OAuth

Не добавляйте Bearer или Basic. Значением Authorization является сам токен SelSup.

Первый запрос · cURL
curl --request GET 'https://api.selsup.ru/api/brand/find?limit=50&page=1' \
  --header 'Authorization: YOUR_API_TOKEN'

Связанные методы API

GET/api/brand/findБезопасный тестовый запрос

02

Ошибки и локаль сообщения

Логику стройте по стабильному полю error, а localMessage показывайте человеку.

Прикладная ошибка обычно содержит error, localMessage и params. Текст localMessage переводится сервером по полю lang пользователя, которому принадлежит токен.

Язык страницы документации и Accept-Language не меняют язык ошибки. Не сравнивайте localMessage в коде и не сохраняйте его как машинный статус.

i
Что сохранить для диагностики

Записывайте HTTP-статус, error, params, время запроса и свой correlation ID. Токен и персональные данные в лог не помещайте.

Контракт прикладной ошибки · JSON
{
  "error": "brand_already_exists",
  "localMessage": "Бренд Base уже существует",
  "params": {
    "name": "Base"
  }
}

03

Пагинация больших справочников

Используйте стабильную сортировку и завершайте выборку по hasNextPage или размеру страницы.

Параметр count=true может запускать дополнительный подсчёт. Передавайте его в первом запросе, только если вам действительно нужен total.

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

Цикл выборки · JavaScript
let page = 1;
let hasNextPage = true;

while (hasNextPage) {
  const url = new URL('https://api.selsup.ru/api/brand/find');
  url.searchParams.set('limit', '500');
  url.searchParams.set('page', String(page));
  url.searchParams.set('sortBy', 'BRANDID');
  url.searchParams.set('ascending', 'true');

  const response = await fetch(url, {
    headers: { Authorization: process.env.SELSUP_API_TOKEN }
  });
  if (!response.ok) throw await response.json();

  const result = await response.json();
  await savePage(result.rows);
  hasNextPage = result.hasNextPage;
  page += 1;
}

Связанные методы API

GET/api/brand/findПример пагинируемого поискаGET/api/product/findПоиск товаров

04

Чек-лист перед production

  1. 1

    Разделите чтение и запись

    Сначала проверьте GET-запросы. Для мутаций используйте тестовые сущности и отдельное подтверждение в вашем интерфейсе.

  2. 2

    Настройте таймауты и повторы

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

  3. 3

    Ограничьте параллелизм

    Учитывайте лимиты конкретного метода, используйте очередь и экспоненциальную задержку с небольшим случайным смещением.

  4. 4

    Сделайте сверку

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

!
Реальные данные

Кнопка «Попробовать» отправляет запрос в аккаунт токена. Методы записи в документации требуют дополнительного подтверждения, но всё равно используйте тестовые записи.