--- title: "API документація MTP Fulfillment — REST, OpenAPI, Postman" description: "REST API MTP Group для e-commerce: автентифікація, замовлення, склад, Нова Пошта. OpenAPI 3.1, Postman collection, Swagger пісочниця — інтеграція за 1 день." lang: uk canonical: https://www.fulfillmentmtp.com.ua/ua/api-docs/ generated: 2026-06-15T12:17:01.155Z --- REST API · OpenAPI 3.1 · v1.0 # Підключіть склад до свого магазину за 1 день Повний REST API для e-commerce інтеграторів: замовлення, склад, доставка Новою Поштою та Укрпоштою, статуси в реальному часі. 18 методів, JSON, HTTPS. [Завантажити OpenAPI 3.1](/openapi.json) [Postman Collection](/files/mtp-api.postman_collection.json) [Відкрити пісочницю ↓](#playground) ✓ Менеджер видасть ключ та допоможе з інтеграцією [Або напишіть в Telegram →](https://t.me/nikolay_mtp?text=%D0%9F%D1%80%D0%B8%D0%B2%D1%96%D1%82!%20%D0%A6%D1%96%D0%BA%D0%B0%D0%B2%D0%B8%D1%82%D1%8C%20%D1%84%D1%83%D0%BB%D1%84%D1%96%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%BE%D0%B7%D1%80%D0%B0%D1%85%D1%83%D0%B2%D0%B0%D1%82%D0%B8%20%D0%B2%D0%B0%D1%80%D1%82%D1%96%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 — 5 хвилин до першого запиту API MTP Fulfillment працює на двох базових URL: основний (замовлення, склад, товари) і v2 (заявки на приймання). Всі запити — `POST`, body у JSON, автентифікація через поле `ApiKey` в тілі запиту. 1 ### Отримайте ApiKey Напишіть вашому менеджеру або використайте метод `GetToken` з обліковими даними. Ключ діє до відкликання. 2 ### Імпортуйте колекцію Завантажте [Postman Collection](/files/mtp-api.postman_collection.json) або [OpenAPI 3.1 JSON](/openapi.json) і відкрийте у вашому інструменті. 3 ### Зробіть тестовий запит Викличте `AddOrder` з тестовими даними. Ми повернемо ID замовлення та статус. В пісочниці нижче можна спробувати без коду. 4 ### Налаштуйте webhook статусів Підпишіться на `ReportStatusOrder`, щоб отримувати зміни статусів (новий → зібраний → відправлений → доставлений). 02 ## Автентифікація API використовує простий ApiKey у тілі кожного запиту. **Не у заголовку** — саме у JSON body як поле `ApiKey`. Такий дизайн історично склався під 1С-інтеграції і зберігається для сумісності. 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 у серверному середовищі — ніколи у JS браузера. Ротуйте ключі раз на 90 днів. Для тестів попросіть менеджера окремий stage-ключ. 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`) — не частіше ніж 1 раз на хвилину. Перевищення дає HTTP 429. 07 ## 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 контролем. ## Корисне поруч [Калькулятор вартості_Розрахуйте вартість для вашого обсягу →_](/ua/calculator/) [Послуги фулфілменту_Склад, комплектація, доставка, повернення →_](/ua/3pl-logistyka/) [FAQ загальний_30+ відповідей про фулфілмент →_](/ua/faq/) [Що таке фулфілмент_Повний гайд для підприємців →_](/ua/shcho-take-fulfilment/)