Начало работы и авторизация

Что нужно сделать до старта работы с продажами (регистрация, подтверждение ассортимента) — в разделе «Начало работы» Академии.

Как устроена авторизация

Доступ к API открывается по токену. Токен вы получаете по протоколу OAuth 2.0. Токен живёт ограниченное время, поэтому его нужно периодически обновлять.

Порядок работы

1. Получите ключи и sellerId

Запросите у менеджера (KAM) или в поддержке client_id, client_secret и sellerId. Один комплект ключей работает со всеми методами API — заводить отдельные ключи под разные задачи не нужно.

2. Получите токен

• POST /v2/auth-token — выпускает токен. В теле запроса передайте grant_type (client_credentials), client_id и client_secret. В ответ придут access_token, expires_in (время жизни в секундах), token_type (bearer) и scope (выданные права).

Время жизни токена expires_in возвращается в ответе POST /v2/auth-token. Значение expires_in может меняться. Поэтому всегда используйте срок жизни токен именно из параметра expires_in.

3. Сделайте первый вызов

Подставьте access_token в заголовок Authorization: Bearer, а sellerId — в параметры метода. Этого достаточно для первого запроса.

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

Токен действует expires_in секунд из ответа. Любой защищённый запрос с истёкшим или неверным токеном вернёт 401 UNAUTHORIZED. Чтобы это не мешало работе, обновляйте токен по следующему правилу:

1. Заранее обновляйте токен, не дожидаясь конца срока — например, за 30–60 c до истечения expires_in.
2. По факту HTTP-ошибки 401. В этом случае, выпустите токен заново и повторите исходный запрос.
3. Не держите токен в кэше дольше expires_in и не задавайте срок жизни константой.

Сквозные соглашения

Следующие правила действуют во всех API-методах:

• Именование полей. Поля и параметры — в camelCase; единственное исключение — тело OAuth-запроса (snake_case).
• Пагинация. Списочные методы принимают page и limit. Предельный размер страницы зависит от метода: у заказов, отгрузок и возвратов — по умолчанию 100, максимум 1000; у номенклатур и минимальных цен — максимум 25. Сколько всего записей и страниц — смотрите в meta (total, page, limit, totalPages).
• Сортировка. Параметр sort; какие значения допустимы, зависит от метода.
• Суммы. Всегда в минорных единицах валюты целым числом — копейки для RUB и BYN, тиыны для KZT.

Формат ошибок

Все ошибки приходят в единой обёртке { "error": { code, message, details? } }, где code — строковый код ошибки, message — текст для человека, а details[] — детали валидации по полям ({ field, issue }).

Возможные коды и соответствующие им HTTP-статусы:

• 400 VALIDATION_FAILED — не прошла валидация;
• 401 UNAUTHORIZED — токен не передан или недействителен;
• 403 FORBIDDEN — доступ запрещён;
• 404 NOT_FOUND — объект не найден;
• 429 TOO_MANY_REQUESTS — слишком много запросов;
• 503 SERVICE_UNAVAILABLE — сервис временно недоступен;
• 500 INTERNAL_SERVER_ERROR — внутренняя ошибка сервиса.

Частые проблемы при подключении

Авторизация — одна из самых частых причин обращений в поддержку. Если что-то не заработало сразу, проверьте в первую очередь эти три вещи:

• 401 со свежим токеном. Скорее всего, токен ушёл в query-параметр вместо заголовка. Передавайте его только через Authorization: Bearer.
• 403 FORBIDDEN — переданный в метод sellerId не соответствует вашему токену. Токен выдаётся под конкретного селлера, поэтому любой чужой или несуществующий sellerId приведет к ошибке 403. Используйте свой sellerId.

См. также

• Обзор Lamoda Seller Partner API
• Каталог: карточки товаров и цены
• Синхронизация и события
• Продажа со своего склада (FBS)
• Частые вопросы (FAQ)