Интеграция по API

Получение Bearer-токена. Токен живёт ~1 час (expires_in в секундах), обновляйте по расписанию, не запрашивайте перед каждым вызовом. Параметры передаются как application/x-www-form-urlencoded, grant_type — client_credentials.

Полученный access_token передаётся в заголовке Authorization: Bearer <token> во всех последующих запросах.

Перед созданием заказов необходимо создать хотя бы один склад, его warehouse_id (UUID) передаётся в запросе создания заказа. Также нужен для return_warehouse_id при возврате. Склады можно создавать через ЛК Магнит Пост или через API. Максимум — 100 складов.

Создание склада

Получение списка складов

Возвращает список пунктов выдачи с пагинацией. Из ответа нужно сохранить key выбранного ПВЗ, а также region и city: эти значения передаются в расчёт стоимости и создание заказа без изменений. Поле drop_off_available показывает, поддерживает ли ПВЗ приём посылок через дроп офф.

Ключевые поля для интеграции: key (передаётся как pup_key в создании заказа), region и city (передаются как pup_region и pup_city в расчёт стоимости, строго без изменений). Поле drop_off_available — флаг доступности дроп оффа: передавайте key такого ПВЗ как drop_off_key при создании заказа со сдачей. Сценарий дроп оффа →

Два режима расчёта. Если клиент уже выбрал ПВЗ, передаёте city_from и pup_key. Для предварительного расчёта без выбора ПВЗ: city_from, pup_region и pup_city.

Для оценки курьерской доставки используется тот же роут /api/v2/magnit-post/orders/estimate с параметром delivery_type: courier. Вместо pup_key/pup_region передаются координаты получателя и габариты посылок. Ответ содержит блок courier_delivery с оценкой двух режимов: on_click (получатель сам вызывает курьера через трекинг) и on_time (доставка к выбранному слоту).

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

Оплата при выдаче: только в создании заказа v2. Для каждой посылки указывается billing_type: not_paid: клиент платит при получении, already_paid: заказ уже оплачен. Итоговая сумма в чеке формируется автоматически.

Как формируется сумма к оплате:

Итоговая сумма в чеке = total_sum_for_parcel (not_paid посылок) + delivery_cost. Если все посылки already_paid, взять с клиента только стоимость доставки невозможно.

Несколько грузомест в одном заказе: только в создании заказа v2. Грузоместа передаются массивом parcels. Если barcode не передан, система формирует его автоматически: customer_order_id_1, customer_order_id_2 и т.д.

Курьерская доставка до двери. Два режима: on_click — получатель сам вызывает курьера через страницу трекинга, когда заказ поступит в ПВЗ; on_time — доставка к выбранному временному слоту. Адрес, координаты и комментарий передаются в блоке courier_delivery.

Прежде чем создавать заказ, запросите доступные слоты и стоимость через метод /api/v2/magnit-post/orders/estimate с delivery_type: courier — тот же роут, что и для расчёта до ПВЗ, но вместо pup_key передаются координаты получателя и габариты посылок (подробности в сценарии «Расчёт стоимости и срока доставки»). В ответ вернётся блок courier_delivery с оценкой обоих режимов:

• on_click — поле available (доступен ли режим для адреса), cost и cost_with_vat в копейках, expected_interval с from/to — ожидаемый интервал прибытия курьера. При создании заказа time_slot не передаётся.
• on_time — поле available и массив slots, каждый слот содержит from, to и cost. Выбираете подходящий слот и передаёте его from/to в поле time_slot при создании заказа.

Дроп офф — партнёр самостоятельно приносит посылки в ПВЗ Магнита, без забора со склада. Сначала проверьте drop_off_available в списке ПВЗ GET /api/v2/magnit-post/pickup-points и выберите ПВЗ с true. В запросе на создание заказа передаётся drop_off_key — ключ этого ПВЗ. Остальные поля — как при стандартном создании: pickup_point (ПВЗ назначения), recipient, parcels.

C2C (consumer-to-consumer) — физическое лицо отправляет посылку другому физлицу через ПВЗ Магнита. Создание заказа — стандартный роут /api/v2/magnit-post/orders, но с двумя новыми параметрами: блок sender с данными отправителя (first_name, last_name, phone) и drop_off_key — ключ ПВЗ, куда отправитель принесёт посылку для сдачи.

Чтобы узнать, на какой ПВЗ можно сдать C2C-посылку, вызовите список ПВЗ GET /api/v2/magnit-post/pickup-points и отфильтруйте по drop_off_available: true. Значение key подходящего ПВЗ передавайте как drop_off_key. ПВЗ назначения, куда посылка будет доставлена получателю, — в поле pickup_point как при стандартном заказе.

Отмена заказа в логистике, возможна только через метод v2 для отмены заказов: в order_id передаётся трек-номер заказа, в parcelIds: id посылок, которые нужно отменить.

Успешный ответ: 204 No Content. Номер заказа (customer_order_id) после отмены повторно использовать нельзя.

Обновление данных уже созданного заказа. В URL передаётся tracking_number или customer_order_id. Конкретную посылку в массиве система находит по barcode. Какие поля доступны и до какого статуса, в таблице ниже.

Если получатель не успевает забрать заказ в стандартный срок хранения на ПВЗ, можно продлить его через API. В параметре order_id передаётся трек-номер или баркод заказа, продление применяется сразу ко всем посылкам этого заказа. Продлить заказ можно только 1 раз, срок продления всегда + 5 дней.

Успешный ответ: 200 OK. Новый срок хранения станет виден в поле storageEndDate при следующем запросе статуса заказа, причём у каждой посылки в заказе.

Пять методов для работы с данными заказов, от batch-проверки статусов до полной истории посылки. Все v1-методы принимают id посылки (UUID из массива parcels[].id), метод v2: tracking_number заказа. Полная статусная модель →

Batch-запрос статусов посылок

Список заказов с фильтрами

Удобен для отладки и поиска конкретных заказов. Поддерживает фильтрацию по customerOrderId, externalOrderId, статусу, дате создания. Пагинация: page (от 1) и size (1-1000).

История статусов посылки

Возвращает массив всех смен статусов с временными метками, полезно для отладки и трекинга.

Данные заказа со всеми посылками (v2)

Единственный метод, который возвращает агрегированный статус заказа. Принимает tracking_number, возвращает все посылки с их id, сохраняйте их для работы с v1-методами.

У партнёра есть три способа отслеживать заказ: через публичную страницу трекинга, через трек-ссылки из API или собрав длинную ссылку самостоятельно.

Публичная страница трекинга

Страница post.magnit.ru/tracking, клиент или партнёр вводит customer_order_id и 4 последние цифры номера получателя. Удобно, когда под рукой нет tracking_number.

Трек-ссылки через API

В ответе GET /api/v2/magnit-post/orders/{tracking_number} возвращаются два поля: tracking_link: короткая ссылка на отслеживание, full_tracking_link: длинная ссылка с полным tracking_number.

Сборка ссылки самостоятельно

Длинную ссылку можно собрать без запроса к API, подставьте tracking_number в шаблон:

Возвращает PDF-файл со всеми этикетками заказа. Параметр {order_id} в пути, это идентификатор посылки (UUID) из массива parcels[].id, который возвращается при создании заказа или через GET /api/v2/magnit-post/orders/{tracking_number}.

Возможные ошибки: 404: заказ не найден или этикетка ещё не сформирована (повторите запрос позже); 401: невалидный или истекший токен; 400: некорректный формат формат order_id.

Только в создании заказа v2. Название компании, которое получатель видит в SMS с кодом выдачи. Полезно, если работаете под несколькими брендами.