REST API · OpenAPI 3.1 · v1.0

Підключіть склад
до свого магазину
за 1 день

Повний REST API для e-commerce інтеграторів: замовлення, склад, доставка Новою Поштою та Укрпоштою, статуси в реальному часі. 18 методів, JSON, HTTPS.

Завантажити OpenAPI 3.1 Postman Collection Відкрити пісочницю ↓

✓ Менеджер видасть ключ та допоможе з інтеграцією

Або напишіть в Telegram →

18REST методів

7груп ендпоінтів

99.5%SLA uptime

<300мсp95 latency

Quick Start Автентифікація Ендпоінти Приклади коду Пісочниця Помилки FAQ

Quick Start — 5 хвилин до першого запиту

API MTP Fulfillment працює на двох базових URL: основний (замовлення, склад, товари) і v2 (заявки на приймання). Всі запити — POST, body у JSON, автентифікація через поле ApiKey в тілі запиту.

Отримайте ApiKey

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

Імпортуйте колекцію

Завантажте Postman Collection або OpenAPI 3.1 JSON і відкрийте у вашому інструменті.

Зробіть тестовий запит

Викличте AddOrder з тестовими даними. Ми повернемо ID замовлення та статус. В пісочниці нижче можна спробувати без коду.

Налаштуйте webhook статусів

Підпишіться на ReportStatusOrder, щоб отримувати зміни статусів (новий → зібраний → відправлений → доставлений).

Автентифікація

API використовує простий ApiKey у тілі кожного запиту. Не у заголовку — саме у JSON body як поле ApiKey. Такий дизайн історично склався під 1С-інтеграції і зберігається для сумісності.

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 у серверному середовищі — ніколи у JS браузера. Ротуйте ключі раз на 90 днів. Для тестів попросіть менеджера окремий stage-ключ.

Групи ендпоінтів

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).

Для роботи пісочниці потрібен JavaScript. Без JS скористайтеся Postman Collection.

Помилки та обмеження

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) — не частіше ніж 1 раз на хвилину. Перевищення дає HTTP 429.

FAQ для розробників

Чи є sandbox-середовище?

Так. Менеджер видає окремий stage-ApiKey, дані з нього не потрапляють на виробничий склад. Той самий URL, інший ключ.

Як підписатися на webhook зміни статусу?

Напишіть URL у карточку вашої інтеграції — наш сервер буде POST-ити JSON на нього при кожній зміні статусу. Ретраї 3 рази з експоненційним бекофом.

Чи підтримуєте GraphQL?

Ні, тільки REST. GraphQL не в roadmap — 18 методів не виправдовують накладні витрати.

Чи є офіційний SDK?

Поки ні. Бібліотеки для Node.js і PHP — у roadmap на 2026 Q3. Поточний обхід — ваш власний HTTP-клієнт.

Як інтегрувати з Prom.ua / Rozetka / Horoshop?

Horoshop має готовий модуль — запитайте менеджера. Для Prom/Rozetka — пишіть свій connector поверх нашого API; типово тиждень роботи одного розробника.

Чи підтримуєте масові операції (batch)?

Частково — AddOrder приймає масив замовлень в одному запиті до 100 шт. Для більших обсягів — черга на вашій стороні з rate-limit контролем.

Підключіть складдо свого магазинуза 1 день