REST API · OpenAPI 3.1 · v1.0

Склад в Украине —
доступ из СНГ
через одно API

Интегрируйте магазин из Казахстана, Молдовы, Грузии или России-в-изгнании с нашим украинским складом. 18 REST методов, JSON, HTTPS. Документация на русском — с прицелом на мультирыночную логистику.

Скачать OpenAPI 3.1 Postman Collection Открыть песочницу ↓

✓ Менеджер выдаст ключ и поможет с интеграцией

Или напишите в Telegram →

18REST методов

7групп эндпоинтов

99.5%SLA uptime

<300мсp95 latency

Quick Start Аутентификация Эндпоинты Примеры кода Песочница Ошибки FAQ

Quick Start — от регистрации до первого заказа

Если вы интегратор из Казахстана, Молдовы или любой другой страны СНГ — сценарий стандартный: получаете ApiKey, подключаете методы заказов, настраиваете webhook статусов. Трансграничная доставка Новой Почтой работает в штатном режиме, таможня — отдельный процесс, который мы помогаем настроить.

Запросите ApiKey

Напишите менеджеру или используйте метод GetToken со своими учётными данными. Ключ не привязан к IP.

Импортируйте коллекцию

Загрузите Postman Collection или OpenAPI 3.1 JSON.

Протестируйте на stage

Менеджер выдаст stage-ключ. Вызовите AddOrder с тестовыми данными — мы вернём ID заказа.

Подпишитесь на webhook

Укажите URL для получения статусов. При каждом изменении мы POST-им JSON: новый → собран → отправлен → доставлен.

Аутентификация

API принимает ApiKey в теле запроса, а не в HTTP-заголовке. Это исторический дизайн под 1С-интеграции, сохранённый ради обратной совместимости. В каждом запросе передавайте поле ApiKey в корне JSON.

POST /GetToken — получить ApiKey

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 используйте секреты переменных окружения.

Группы эндпоинтов

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 — реквизиты отправителя

Примеры кода

Готовые сниппеты создания заказа. Подставьте ApiKey, адаптируйте поля под свой магазин.

cURL — создание заказа

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 — создание заказа

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 — создание заказа

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']

Интерактивная песочница

Swagger UI ниже читает OpenAPI 3.1 спецификацию и позволяет вызывать любой метод прямо со страницы. Для боевых запросов подставьте свой ApiKey в тело запроса. Без ключа работают только справочные методы (getCities, getWarehouses).

Ошибки и лимиты

API возвращает HTTP 200 для всех валидных запросов — статус операции в теле ответа через строковое поле result. Сетевые ошибки (400/401/500) возникают только при неправильном URL или сломанном JSON.

Структура ответа

{
  "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.

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 контролем.

Склад в Украине —доступ из СНГчерез одно API