--- title: "API документация MTP Fulfillment — REST, OpenAPI, Postman" description: "REST API MTP Group для СНГ-интеграторов (Казахстан, Молдова, Грузия): заказы, склад в Украине, Новая Почта. OpenAPI 3.1, Postman, Swagger песочница — 1 день интеграции." lang: ru canonical: https://www.fulfillmentmtp.com.ua/ru/api-docs/ generated: 2026-06-15T12:17:00.691Z --- REST API · OpenAPI 3.1 · v1.0 # Склад в Украине — доступ из СНГ через одно API Интегрируйте магазин из Казахстана, Молдовы, Грузии или России-в-изгнании с нашим украинским складом. 18 REST методов, JSON, HTTPS. Документация на русском — с прицелом на мультирыночную логистику. [Скачать OpenAPI 3.1](/openapi.json) [Postman Collection](/files/mtp-api.postman_collection.json) [Открыть песочницу ↓](#playground) ✓ Менеджер выдаст ключ и поможет с интеграцией [Или напишите в Telegram →](https://t.me/nikolay_mtp?text=%D0%97%D0%B4%D1%80%D0%B0%D0%B2%D1%81%D1%82%D0%B2%D1%83%D0%B9%D1%82%D0%B5!%20%D0%98%D0%BD%D1%82%D0%B5%D1%80%D0%B5%D1%81%D1%83%D0%B5%D1%82%20%D1%84%D1%83%D0%BB%D1%84%D0%B8%D0%BB%D0%BC%D0%B5%D0%BD%D1%82.%20%D0%9C%D0%BE%D0%B6%D0%B5%D1%82%D0%B5%20%D1%80%D0%B0%D1%81%D1%81%D1%87%D0%B8%D1%82%D0%B0%D1%82%D1%8C%20%D1%81%D1%82%D0%BE%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D1%8C%3F) 18REST методов 7групп эндпоинтов 99.5%SLA uptime <300мсp95 latency [Quick Start](#quickstart) [Аутентификация](#auth) [Эндпоинты](#endpoints) [Примеры кода](#examples) [Песочница](#playground) [Ошибки](#errors) [FAQ](#faq) 01 ## Quick Start — от регистрации до первого заказа Если вы интегратор из Казахстана, Молдовы или любой другой страны СНГ — сценарий стандартный: получаете ApiKey, подключаете методы заказов, настраиваете webhook статусов. Трансграничная доставка Новой Почтой работает в штатном режиме, таможня — отдельный процесс, который мы помогаем настроить. 1 ### Запросите ApiKey Напишите менеджеру или используйте метод `GetToken` со своими учётными данными. Ключ не привязан к IP. 2 ### Импортируйте коллекцию Загрузите [Postman Collection](/files/mtp-api.postman_collection.json) или [OpenAPI 3.1 JSON](/openapi.json). 3 ### Протестируйте на stage Менеджер выдаст stage-ключ. Вызовите `AddOrder` с тестовыми данными — мы вернём ID заказа. 4 ### Подпишитесь на webhook Укажите URL для получения статусов. При каждом изменении мы POST-им JSON: новый → собран → отправлен → доставлен. 02 ## Аутентификация API принимает ApiKey **в теле запроса**, а не в HTTP-заголовке. Это исторический дизайн под 1С-интеграции, сохранённый ради обратной совместимости. В каждом запросе передавайте поле `ApiKey` в корне JSON. POST /GetToken — получить ApiKeyCopy ``` curl -X POST 'https://fulfillment.in.ua:34443/MTPGroupFulfillment/hs/api/GetToken' \ -H 'Content-Type: application/json' \ -d '{ "login": "your_login", "password": "your_password" }' # Ответ: # { # "result": "ok", # "Data": { "ApiKey": "9a2c46ab-f629-46b4-88ce-..." }, # "errors": [] # } ``` **Безопасность:** храните ApiKey в серверной среде — никогда в JavaScript браузера. Ротация раз в 90 дней. Для CI/CD используйте секреты переменных окружения. 03 ## Группы эндпоинтов API сгруппировано по доменным моделям. Полный список параметров и ответов — в OpenAPI спецификации. ### Auth 1 метод - `GetToken` — получить ApiKey по логину/паролю ### Orders 6 методов - `AddOrder` — создать клиентский заказ - `EditOrder` — редактировать до сборки - `CancelOrder` — отменить заказ - `ReportStatusOrder` — список изменений статусов за период - `getStatusOrder` — текущий статус одного заказа - `ListOrder` — реестр заказов ### Products 1 метод - `AddProduct` — добавить SKU в каталог ### Inventory 2 метода - `ReportSklad` — остатки на складе - `ReportMoveProduct` — движения товаров за период ### Delivery 3 метода (v2) - `ListDeliveryRequest` — список заявок на приёмку - `AddDeliveryRequest` — новая заявка - `ReportDeliveryRequest` — отчёт по заявкам ### Returns 1 метод - `ListReturnOrder` — реестр возвратов ### Reference 4 метода - `getCities` — справочник городов Новой Почты - `getWarehouses` — отделения в городе - `getStreet` — улицы для адресной доставки - `senderDetails` — реквизиты отправителя 04 ## Примеры кода Готовые сниппеты создания заказа. Подставьте ApiKey, адаптируйте поля под свой магазин. cURL — создание заказаCopy ``` curl -X POST 'https://fulfillment.in.ua:34443/MTPGroupFulfillment/hs/api/AddOrder' \ -H 'Content-Type: application/json' \ -d '{ "ApiKey": "YOUR_API_KEY", "order": { "id_order": "WEB-10542", "external_id": "WEB-10542", "date_order": "21.06.2026", "recipient": "Петров Алексей", "rec_phone": "380501234567", "comment": "комментарий клиента", "Cost": 550, "PayerType": "Recipient", "payment_method": "Наличными", "order_payment_sum": "550", "delivery_method": "Новая Почта", "delivery_address": { "WarehouseRef": "d7108df0-8433-11e4-acce-0050568002cf" }, "products": [ { "sku": "TSHIRT-BLK-L", "name": "Футболка чёрная L", "count": "1", "price": "550" } ] } }' # Ответ: # { # "result": "ok", # "Data": { "id_order_FF": "AVS316017", "key_order": "uuid-..." }, # "errors": [] # } ``` Node.js — создание заказаCopy ``` const res = await fetch('https://fulfillment.in.ua:34443/MTPGroupFulfillment/hs/api/AddOrder', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ApiKey: process.env.MTP_API_KEY, order: { id_order: order.id, external_id: order.id, date_order: order.dateDDMMYYYY, recipient: order.recipientFullName, rec_phone: order.phone, // формат 380XXXXXXXXX comment: order.comment || '', Cost: order.declaredValue, // целое число PayerType: 'Recipient', // или 'Sender' payment_method: 'Наличными', // или 'На карту' (если предоплачено) order_payment_sum: String(order.codAmount || order.total), delivery_method: 'Новая Почта', delivery_address: { WarehouseRef: order.warehouseRef }, products: order.items.map(i => ({ sku: i.sku, name: i.name, count: String(i.qty), price: String(i.price) })) } }) }); const data = await res.json(); if (data.result !== 'ok') throw new Error(JSON.stringify(data.errors)); const ourOrderId = data.Data.id_order_FF; ``` Python — создание заказаCopy ``` import os, requests r = requests.post( 'https://fulfillment.in.ua:34443/MTPGroupFulfillment/hs/api/AddOrder', json={ 'ApiKey': os.environ['MTP_API_KEY'], 'order': { 'id_order': order['id'], 'external_id': order['id'], 'date_order': order['date_ddmmyyyy'], 'recipient': order['recipient_full_name'], 'rec_phone': order['phone'], # 380XXXXXXXXX 'comment': order.get('comment', ''), 'Cost': order['declared_value'], # int 'PayerType': 'Recipient', # 'Sender' или 'Recipient' 'payment_method': 'Наличными', # или 'На карту' 'order_payment_sum': str(order.get('cod_amount', order['total'])), 'delivery_method': 'Новая Почта', 'delivery_address': {'WarehouseRef': order['warehouse_ref']}, 'products': [ {'sku': i['sku'], 'name': i['name'], 'count': str(i['qty']), 'price': str(i['price'])} for i in order['items'] ] } } ) r.raise_for_status() data = r.json() if data['result'] != 'ok': raise RuntimeError(data['errors']) our_order_id = data['Data']['id_order_FF'] ``` 05 ## Интерактивная песочница Swagger UI ниже читает OpenAPI 3.1 спецификацию и позволяет вызывать любой метод прямо со страницы. Для боевых запросов подставьте свой `ApiKey` в тело запроса. Без ключа работают только справочные методы (getCities, getWarehouses). 06 ## Ошибки и лимиты API возвращает HTTP 200 для всех валидных запросов — статус операции в теле ответа через строковое поле `result`. Сетевые ошибки (400/401/500) возникают только при неправильном URL или сломанном JSON. Структура ответаCopy ``` { "result": "ok", // или "error" "Data": { ... }, // полезная нагрузка если result="ok" "errors": [ ... ] // массив ошибок если result="error" } ``` | Поле / код | Значение | Что делать | | --- | --- | --- | | `result: "ok"` | Операция успешна | Читайте `Data` | | `result: "error"` | Бизнес-ошибка | Читайте массив `errors` — там описание проблемы | | HTTP `401` | Неверный ApiKey | Проверьте поле `ApiKey` в теле (не в заголовке!) | | HTTP `400` | Неправильный JSON | Проверьте синтаксис тела запроса | | HTTP `404` | Неизвестный метод | Проверьте URL — корректный путь `/api/{МЕТОД}` | | HTTP `429` | Rate limit | Снизьте частоту запросов (см. ниже) | | HTTP `5xx` | Ошибка сервера | Повторите позже или напишите менеджеру | **Rate limits:** 60 запросов/минута на ApiKey. Для отчётных методов (`ReportSklad`, `ReportStatusOrder`, `ListOrder`, `ListReturnOrder`) — не чаще одного раза в минуту. Превышение даёт HTTP 429. 07 ## FAQ для разработчиков ### Есть ли sandbox? Да. Менеджер выдаёт stage-ApiKey. Тот же URL, другой ключ — данные не попадают на боевой склад. ### Как подписаться на webhook статусов? Укажите URL в карточке интеграции. Мы POST-им JSON при каждом изменении статуса. Ретраи 3 раза с экспоненциальным бэкоффом. ### Поддерживаете ли GraphQL? Нет, только REST. GraphQL не в roadmap — 18 методов не оправдывают overhead. ### Есть ли официальный SDK? Пока нет. Библиотеки для Node.js и PHP — в roadmap на 2026 Q3. Текущий обход — ваш собственный HTTP-клиент. ### Как интегрировать с маркетплейсом из СНГ? Kaspi.kz / OZON / Wildberries — пишите свой connector поверх нашего API. Типично неделя работы разработчика. Таможенные нюансы — отдельный процесс, помогаем. ### Поддерживаются ли массовые операции (batch)? Частично — AddOrder принимает массив до 100 заказов в одном запросе. Для больших объёмов — очередь на вашей стороне с rate-limit контролем. ## Полезное рядом [Калькулятор стоимости_Рассчитайте для вашего объёма →_](/ru/calculator/) [Услуги фулфилмента_Склад, сборка, доставка, возвраты →_](/ru/services/) [FAQ общий_30+ ответов о фулфилменте →_](/ru/faq/) [Что такое фулфилмент_Полный гайд для предпринимателей →_](/ru/chto-takoe-fulfilment/)