Заявки на транспорт (FBS)

API заявок на транспорт позволяет получать заявки на доставку и возврат товаров по модели FBS, создавать и редактировать заявки dropoff, просматривать транспортный пропуск и отменять pickup-заявки — без ручной работы в Lamoda Seller. Шаг «Обрабатывайте заявки на вывоз» общего потока описан в статье «Продажа со своего склада (FBS)»; здесь — детали работы с заявками.

Эта статья описывает порядок работы с методами и ключевые бизнес-правила. Параметры, полный состав полей и примеры запросов и ответов смотрите в справочнике API на странице соответствующего метода.

Общие правила авторизации и формат ошибок описаны в статье «Начало работы и авторизация». Во всех запросах передавайте JWT в заголовке Authorization: Bearer <token>. Идентификатор sellerId должен соответствовать продавцу, доступному токену.

Как работать с заявками

Определите способ передачи товаров: PICKUP — забор со склада продавца, DROPOFF — самостоятельная доставка на базовый склад. Способ передачи товаров для доставки товаров на склад Lamoda и для забора возвратов может быть разный.

Заявки PICKUP создаются Lamoda автоматически, по настроенному расписанию продавца и при поступлении новых заказов/возвратов. Для заявок DROPOFF есть возможность создать за один раз две заявки — в одной привезти отгрузку, а во второй (связанной) забрать возвраты.

Просмотр заявок:

1. Получите общий список заявок и сохраните id нужной заявки.
2. Запросите заявку по id, чтобы проверить статус, возможность редактирования и данные транспортного пропуска.

Создание и редактирование:

• Dropoff-заявки можно создавать через API. При необходимости можно редактировать практически все поля заявки. Основное содержимое заявки — это транспортный пропуск.
• Pickup-заявки нельзя создавать и редактировать через API, всю информацию по ним заполняет Lamoda. Если транспорт на определенный день не нужен, заявку можно отменить.

Методы для работы с заявками

• GET /v2/fbs/transport-requests — единый список pickup- и dropoff-заявок с фильтрами, пагинацией и сортировкой.
• GET /v2/fbs/transport-requests/{requestId} — заявка и транспортный пропуск.
• POST /v2/fbs/dropoff-requests — создание заявки dropoff.
• POST /v2/fbs/dropoff-requests/{requestId} — редактирование заявки dropoff.
• GET /v2/fbs/pickup-requests — расширенный список pickup-заявок, включая информацию о назначенных курьерах Lamoda и статус возможности отмены.
• POST /v2/fbs/pickup-requests/{requestId}/status — отмена pickup-заявки.
• GET /v2/fbs/warehouses - получение списка складов продавца

Типы, способы передачи и статусы

Тип заявки

Метод доставки

Статус заявки

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

1. Получение общего списка заявок

GET /v2/fbs/transport-requests возвращает pickup- и dropoff-заявки на доставку и возврат. Это основной метод для поиска заявки и восстановления её id.

Массивы в query передаются повторением параметра, например:

GET /v2/fbs/transport-requests?sellerId=123&statuses=NEW&statuses=ACTIVE
&deliveryMethods=DROPOFF&sort=-date

В каждом элементе ответа приходят id, status, type, deliveryMethod и date. Поле shipmentIds присутствует только у заявок DELIVERY; у RETURN его нет. Данные пагинации находятся в meta.

2. Получение заявки по id

GET /v2/fbs/transport-requests/{requestId}?sellerId={sellerId} возвращает одну заявку и связанный транспортный пропуск.

Перед изменением заявки проверьте:

• editability: EDITABLE — заявку можно редактировать, NOT_EDITABLE — нельзя;
• date — плановую дату заявки;
• arrivalAt и departureAt — время прибытия и отбытия на склад Lamoda; поля могут быть null;
• transportPass — сведения для транспортного пропуска и ЭТрН.

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

3. Создание заявки dropoff

POST /v2/fbs/dropoff-requests создаёт заявку на самостоятельную доставку или возврат товаров.

Для создания всегда передавайте:

• sellerId — идентификатор продавца;
• warehouseId — UUID склада, идентификатор склада берется из ответа GET /v2/fbs/warehouses, подходит склад в статусе CREATED и isActive = true;
• date — плановую дату приезда в формате YYYY-MM-DD;
• requestType — DELIVERY или RETURN.

Для requestType=DELIVERY дополнительно обязателен непустой shipmentIds. Для RETURN список отгрузок не требуется.

Чтобы сразу заполнить транспортный пропуск, передайте сведения об участии стороннего перевозчика, подписании ЭТрН экспедитором, типе грузоотправителя, документах, водителях, транспортном средстве и компаниях. Полный набор зависит от схемы перевозки; детали обязательности проверяет сервис заявок.

В успешном ответе возвращаются идентификатор id и состояние status. Если использованоlinkedRequestOption=WITH_RETURN и связанная возвратная заявка создана, ответ также содержит linkedReturnRequestId.

4. Редактирование заявки dropoff

POST /v2/fbs/dropoff-requests/{requestId} изменяет плановую дату и данные транспортного пропуска. В теле обязательны sellerId и date.

• Не переданные необязательные поля считаются незаполненными.
• Не переданные documents, couriers, companies и явно переданные пустые массивы очищают соответствующие списки.
• Не переданный vehicle означает отсутствие данных транспортного средства.
• etrnSignedByExpeditor: null обрабатывается как незаполненное значение.
• linkedRequestAction=UNLINK отвязывает связанную возвратную заявку. Повторно связать эти же заявки через update нельзя.

Заявка в состоянии NEW останется NEW, если после обновления данных по-прежнему недостаточно для ЭТрН. Активную заявку нельзя сделать неполной: сервис вернёт ошибку валидации. В успешном ответе приходят id и новый status.

Перед обновлением получите карточку заявки, убедитесь, что editability=EDITABLE, и отправьте обратно все данные транспортного пропуска, которые должны сохраниться.

5. Получение расширенного списка pickup-заявок

GET /v2/fbs/pickup-requests полезен, когда нужны данные, специфичные для забора со склада: временной интервал прибытия, назначенные курьеры и возможность отмены.

Метод поддерживает фильтры dateFrom, dateTo, точную дату date, тип type, статусы statuses, пагинацию и сортировку по date или -date. Для этого метода обе границы периода dateFrom и dateTo включаются.

6. Отмена pickup-заявки

POST /v2/fbs/pickup-requests/{requestId}/status изменяет статус pickup-заявки. Сейчас поддерживается только целевой статус CANCELLED.

{"sellerId": "123", "status": "CANCELLED"}

При успешной отмене метод возвращает 200 OK без тела. Перед вызовом проверьте cancellationAvailability в расширенном списке pickup-заявок.

7. Получение списка складов продавца

GET /v2/fbs/warehouses возвращает список складов продавца с пагинацией. Для проверки прав доступа необходимо передать sellerId.

Ошибки

Все методы используют общий формат ошибки: объект error с полями code, message и, при наличии, details[]. Исправляйте данные по полям details[].field и details[].issue.

Рекомендации

• Сохраняйте идентификаторы. После создания сохраните id и, если он пришёл, linkedReturnRequestId.
• Используйте единый список для синхронизации. Он возвращает заявки обоих способов передачи и подходит для регулярного обновления локального состояния.
• Перед update получайте карточку. Проверьте editability и сформируйте полное целевое состояние транспортного пропуска, чтобы случайно не очистить данные.
• Различайте границы дат. В едином списке dateTo не включается, а в расширенном pickup-списке включается.
• Не ожидайте shipmentIds у возврата. Для заявок RETURN поле отсутствует.
• Обрабатывайте временные ошибки. Для 429 и 503 используйте повторные запросы с увеличивающейся задержкой.

Смотри также

• Продажа со своего склада (FBS)
• Начало работы и авторизация