Lamoda через API и MCP: 68 методов, три конкурирующих API у одного поставщика и путь без слэша

Обзор

У Lamoda для партнёров-продавцов не один API, а три, и они не заменяют друг друга — они накапливались. Legacy JSON-RPC API работал с каталогом (товары, цены, остатки) через единственный endpoint /jsonrpc и конверт {"jsonrpc", "method", "params"} вместо обычных путей. Отдельно жил и живёт Lamoda B2B Platform API — полноценный REST на api-b2b.lamoda.ru: заказы, отгрузки, каталог, остатки, этикетки, подарочные сертификаты, партнёрские пункты выдачи. Год спустя поверх обоих начали расти Lamoda Seller REST API v2 — новые возможности (возвраты FBS, вопросы покупателей, акции), которых нет ни в одном из первых двух.

Mira подключает B2B Platform API целиком — 68 методов в тринадцати разделах. Ниже — почему не все три, и что нашлось внутри того одного, который подключён.

Почему не все три API сразу

Схема авторизации — не деталь, а причина решения. B2B Platform API выдаёт токен по POST /auth/token с телом {client_id, client_secret, grant_type: "client_credentials"} — тот же приём, что уже отлажен и протестирован у Ozon Performance. Legacy JSON-RPC API, напротив, требует отдельного вызова v1.tokens.create внутри своего собственного конверта JSON-RPC — это не client_credentials в привычном виде, а вложенный протокол поверх протокола. Seller REST API v2 живёт на том же хосте, что и JSON-RPC-каталог (public-api-seller.lamoda.ru), и собственного endpoint'а для токена в его спецификации нет вовсе — по всем признакам он ждёт токен, выпущенный ИМЕННО тем JSON-RPC-вызовом.

Заводить в Go третью схему выдачи токена ради каталога, который REST API B2B Platform и так дублирует (те же номенклатуры, цены и остатки, только по нормальным путям), — усложнение без выигрыша. Возвраты, вопросы и акции Seller REST API v2 остаются долгом: подключаются отдельно, когда решится, как токен для одного протокола скормить другому без второй пары ключей в форме.

Что доступно продавцу

Опечатка, которую мы не стали чинить

В спецификации B2B Platform API три пути отвечают за способ доставки заказа, и у одного из них, документированного как GET /api/v1/orders{orderNr}/delivery_method, перед {orderNr} нет слэша — везде рядом он есть. Соблазн поправить «очевидную» опечатку в своём коде был, но это чужая документация: если поставщик действительно так резолвит маршрут, «исправленный» путь просто перестанет работать. Метод подключён дословно, с примечанием об этом в описании действия — если он ответит 404, это будет ответ поставщика, а не наша догадка, выданная за факт.

Единый конверт отказа, поданный двумя формами

У всех 68 методов один и тот же конверт ошибки — {code, description, message, errors} — но спецификация сама расходится в том, как он упакован: у /auth/token он объявлен массивом из одного объекта, у /api/v1/nomenclatures — прямо объектом. Разбор отказа принимает обе формы не потому, что мы не уверены, какая правильная, а потому, что поставщик сам документирует разное на разных путях.

Почему деньги здесь — это не барьер, а сертификаты

Ozon Performance — рекламная площадка, и там барьер на тратящих действиях покрывает восемь из пятнадцати меняющих. У Lamoda как канала продаж логика другая: создать заказ, поправить цену или обновить остаток не списывает деньги продавца — это данные о том, что уже случилось или должно случиться, а не расход бюджета. Единственное исключение — подарочные сертификаты: gift_certificate_create выпускает сертификат с суммой и валютой, gift_certificate_payment списывает его в оплату. Это прямое создание и использование денежного инструмента, и барьер здесь тот же, что у любой траты: подтверждение перед действием.

Вебхуки — не наш вызов

В спецификации B2B Platform API есть три пути с говорящим именем «url to receive the request»: это не методы, которые вызываем мы, а описание того, что Lamoda сама пришлёт на адрес нотификаций партнёра — о смене статуса заказа, о прямой или обратной передаче права собственности. Приёмника вебхуков у Mira пока нет, и подключать их значило бы описывать то, что некому принять. Вызов notifications_resend, который ЗАПРАШИВАЕТ у Lamoda повторную отправку такого события, — в таблице; сам приём — нет.

Как это выглядит из чата

Продавец пишет: «Какие заказы Lamoda ждут отгрузки?» — и агент читает список заказов с фильтром по статусу, без единой строки кода на стороне продавца. Ключ подключается один раз в настройках проекта — Client ID и Client Secret выдаёт sales-manager Lamoda, самостоятельно в личном кабинете партнёра их не выпустить.