Рекомендации по надежной интеграции от партнеров

Рекомендации по построению надежной интеграции с Lamoda API, основанные на опыте партнеров.

Авторизация

Обновляйте токен заранее

TTL токена — 15 минут. Обновляйте его за 1-2 минуты до истечения, не дожидаясь 401.

def get_token():
    if token_expires_at - time.time() < 120:  # 2 минуты до истечения
        refresh_token()
return current_token

Кэшируйте токен, но не credentials

Храните токен в памяти или Redis, но client_id/secret — только в защищенном хранилище (env, vault).

Логирование

Логируйте всё

Обязательно сохраняйте для каждого запроса:

• Время запроса (с часовым поясом)
• Метод и URL с query-параметрами
• Тело запроса (для POST)
• Заголовки запроса
• Код и тело ответа
• Время выполнения

Это критически важно для разбора инцидентов с поддержкой.

Не логируйте секреты

Маскируйте в логах: client_secret, access_token, персональные данные клиентов.

Обработка ошибок

Реализуйте retry с exponential backoff

При 5xx или timeout — повторяйте с увеличением интервала:

def request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, timeout=30)
            if response.status_code < 500:
                return response
        except requests.Timeout:
            pass
        
        sleep_time = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(sleep_time)
    
raise Exception("Max retries exceeded")

Различайте типы ошибок

Работа с заказами

Используйте webhooks вместо polling

Webhooks быстрее и надёжнее. Polling используйте как fallback.

Отслеживайте статусы товаров, не только заказов

При частичном выкупе статус заказа "Delivered", но у отдельных товаров может быть "Not bought". Используйте itemStatusChanged нотификации.

Соблюдайте cutOff

Отгружайте заказы максимально близко к cutOff. Если cutOff = null — в ближайшей поставке.

Работа с ценами

Используйте batch-методы

Вместо 1000 отдельных запросов set-price используйте один set-prices с массивом.

Не снижайте цену более чем на 70% без подтверждения

Передавайте force: true только если уверены. Иначе цена попадет в карантин.

Синхронизация остатков

Используйте дельту, не полную выгрузку

Параметр updatedAt возвращает только измененные записи. Это быстрее в 10-100 раз.

# Плохо: весь сток
GET /api/v1/stock/goods?page=1&limit=1000

# Хорошо: только изменения за последний час
GET /api/v1/stock/goods?updatedAt=2025-12-02+09:00:00

Надежность

Делайте идемпотентные запросы

Используйте уникальные ID в запросах. При повторе с тем же ID результат должен быть тот же.

Храните состояние локально

Не полагайтесь только на API — дублируйте критические данные (заказы, отгрузки) в своей БД.

Мониторьте API-вызовы

Отслеживайте:

• Количество ошибок в минуту
• Время ответа (p50, p95, p99)
• Rate limit hits
• Статус webhook-доставки

Чек-лист перед запуском

• Токен обновляется автоматически до истечения
• Логи пишутся для всех запросов/ответов
• Реализован retry с backoff для 5xx
• Webhook endpoint отвечает за < 5 секунд
• Webhook endpoint возвращает 2xx и обрабатывает асинхронно
• Обрабатываются дубли нотификаций (по sequenceNumber)
• warehouse_code передается во всех отгрузках
• Правильный метод для модели (set-price vs update-price)
• Цены кратны 10 рублям
• Материалы в правильном формате (пробел-тире-пробел)
• Есть алерты на рост ошибок
• Документированы все интеграционные точки

Рекомендуемая архитектура

          
   Ваша система     API Gateway      Lamoda API 
                         (retry, log)                     
          
                                
                                
     
   Ваша БД                 Логи         
   (backup)              (Elastic/Loki) 
     
         
         

  Webhook         Lamoda Notifications
  Handler        

См. также

• Распространенные проблемы при работе с API
• Настройка вебхуков
• Коды ошибок