--- title: "MTP Fulfillment API — REST Docs, OpenAPI 3.1, Postman" description: "REST API for Ukraine fulfillment: orders, inventory, Nova Poshta delivery. OpenAPI 3.1 spec, Postman collection, interactive playground. English docs." lang: en canonical: https://www.fulfillmentmtp.com.ua/en/api-docs/ generated: 2026-06-15T12:16:59.741Z --- REST API · OpenAPI 3.1 · v1.0 # Ship to Ukrainian customers from your Shopify store Production REST API for European integrators connecting Shopify, WooCommerce, BigCommerce, or custom stacks to a bonded Ukrainian warehouse. 18 methods, JSON, HTTPS, 99.5% SLA. Gateway to a 40M-consumer market with EU-compatible logistics. [Download OpenAPI 3.1](/openapi.json) [Postman Collection](/files/mtp-api.postman_collection.json) [Open playground ↓](#playground) ✓ Integration manager will issue the key and walk you through setup [Or message us on Telegram →](https://t.me/nikolay_mtp?text=Hi!%20Interested%20in%20fulfillment%20services.%20Can%20you%20calculate%20the%20cost%3F) 18REST methods 7endpoint groups 99.5%uptime SLA <300msp95 latency [Quick Start](#quickstart) [Authentication](#auth) [Endpoints](#endpoints) [Code Examples](#examples) [Playground](#playground) [Errors](#errors) [FAQ](#faq) 01 ## Quick Start — first order in 5 minutes If you run an EU-based Shopify or WooCommerce store and want to ship into Ukraine without a local entity, this API is the shortest path. Request an ApiKey, plug in order and status endpoints, and Nova Poshta handles last-mile delivery. Customs paperwork is a separate workflow — our integration team handles it for you at onboarding. 1 ### Request an ApiKey Contact your integration manager or call `GetToken` with your credentials. The key is bearer-style and does not expire until revoked. 2 ### Import the collection Grab the [Postman Collection](/files/mtp-api.postman_collection.json) or the [OpenAPI 3.1 JSON](/openapi.json). 3 ### Test in staging Your manager issues a staging ApiKey with isolated data. Call `AddOrder` with dummy data; we return the order ID and status. 4 ### Subscribe to status webhooks Register a URL and we POST JSON on every status change (new → picked → shipped → delivered). Retries 3x with exponential backoff. 02 ## Authentication The API expects the ApiKey **in the request body**, not as an HTTP header. This is a legacy design from the original 1C (Ukraine ERP) integrators, preserved for backward compatibility. Include an `ApiKey` field at the root of every JSON body. POST /GetToken — exchange credentials for 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" }' # Response: # { # "result": "ok", # "Data": { "ApiKey": "9a2c46ab-f629-46b4-88ce-..." }, # "errors": [] # } ``` **Security:** store the ApiKey server-side only — never in browser JavaScript. Rotate every 90 days. For CI/CD, use environment secret variables (GitHub Actions, GitLab CI). 03 ## Endpoint groups Endpoints are grouped by domain model. Full parameters and response schemas are in the OpenAPI specification. ### Auth 1 method - `GetToken` — get ApiKey from login/password ### Orders 6 methods - `AddOrder` — create a customer order - `EditOrder` — edit before picking starts - `CancelOrder` — cancel an order - `ReportStatusOrder` — status changes within a period - `getStatusOrder` — current status of one order - `ListOrder` — order register ### Products 1 method - `AddProduct` — add SKU to the catalog ### Inventory 2 methods - `ReportSklad` — warehouse stock levels - `ReportMoveProduct` — goods movement over a period ### Delivery 3 methods (v2) - `ListDeliveryRequest` — list inbound delivery requests - `AddDeliveryRequest` — new inbound delivery - `ReportDeliveryRequest` — report on deliveries ### Returns 1 method - `ListReturnOrder` — return shipments register ### Reference 4 methods - `getCities` — Nova Poshta city directory - `getWarehouses` — branches in a city - `getStreet` — streets for courier delivery - `senderDetails` — sender registration data 04 ## Code examples Ready-to-use snippets for creating orders. Paste your ApiKey, map fields to your store's data model. cURL — create orderCopy ``` 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": "Oleh Petrenko", "rec_phone": "380501234567", "comment": "customer note", "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": "T-Shirt Black L", "count": "1", "price": "550" } ] } }' # Response: # { # "result": "ok", # "Data": { "id_order_FF": "AVS316017", "key_order": "uuid-..." }, # "errors": [] # } ``` Node.js — create orderCopy ``` 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, // e.g. "21.06.2026" recipient: order.recipientFullName, rec_phone: order.phone, // format 380XXXXXXXXX comment: order.comment || '', Cost: order.declaredValue, // integer UAH PayerType: 'Recipient', // or 'Sender' payment_method: 'Наличными', // or 'На карту' if prepaid (Cyrillic literals required) order_payment_sum: String(order.codAmount || order.total), delivery_method: 'Новая Почта', // also: 'Ukrposhta', 'Курьерская доставка Киев', 'Самовывоз' 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 — create orderCopy ``` 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'], # "21.06.2026" 'recipient': order['recipient_full_name'], 'rec_phone': order['phone'], # 380XXXXXXXXX 'comment': order.get('comment', ''), 'Cost': order['declared_value'], # int UAH 'PayerType': 'Recipient', # 'Sender' or 'Recipient' 'payment_method': 'Наличными', # or 'На карту' if prepaid (Cyrillic literal required) 'order_payment_sum': str(order.get('cod_amount', order['total'])), 'delivery_method': 'Новая Почта', # also: 'Ukrposhta', 'Курьерская доставка Киев', 'Самовывоз' '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 ## Interactive playground The Swagger UI below reads our OpenAPI 3.1 spec and lets you fire real requests from this page. For authenticated endpoints, paste your `ApiKey` into the request body. Reference methods (getCities, getWarehouses) work without a key. 06 ## Errors and rate limits The API returns HTTP 200 for all valid requests — operation status is delivered via the string `result` field in the response body. Network-level errors (400/401/500) indicate a wrong URL or malformed JSON, not a business outcome. Response envelopeCopy ``` { "result": "ok", // or "error" "Data": { ... }, // payload when result="ok" "errors": [ ... ] // array of error descriptions when result="error" } ``` | Field / status | Meaning | Action | | --- | --- | --- | | `result: "ok"` | Operation succeeded | Read `Data` for the payload | | `result: "error"` | Business error | Read the `errors` array for description | | HTTP `401` | Invalid ApiKey | Check the `ApiKey` field in body (not headers!) | | HTTP `400` | Malformed JSON | Validate request body syntax | | HTTP `404` | Unknown method | Verify the URL path `/api/{METHOD}` | | HTTP `429` | Rate limit hit | Throttle on your side (see below) | | HTTP `5xx` | Server error | Retry with backoff or contact your manager | **Rate limits:** 60 requests/minute per ApiKey. Reporting endpoints (`ReportSklad`, `ReportStatusOrder`, `ListOrder`, `ListReturnOrder`) are capped at 1/min. Exceeding the limit returns HTTP 429. 07 ## Developer FAQ ### Is there a sandbox environment? Yes. Your integration manager issues a separate staging ApiKey. Same URL, different key — data does not touch the production warehouse. ### How do I subscribe to status webhooks? Register a URL in your integration profile. We POST JSON on every status change. Retries 3x with exponential backoff. ### Do you support GraphQL? No, REST only. GraphQL is not on the roadmap — 18 methods do not justify the overhead. ### Is there an official SDK? Not yet. Node.js and PHP libraries are on the 2026 Q3 roadmap. Current workaround: your own HTTP client around the spec. ### How do I integrate Shopify / WooCommerce? Write a middleware service that listens to Shopify/Woo order webhooks, transforms payloads into our schema, and calls AddOrder. Status updates flow back to Shopify via its Fulfillment API. Typical build: one week for a senior dev. ### Do you support batch operations? Partially — AddOrder accepts an array of up to 100 orders per request. For higher volumes, queue on your side with rate-limit control. ## Related resources [Cost Calculator_Estimate fulfillment cost by volume →_](/en/calculator/) [Fulfillment Services_Storage, pick-pack, delivery, returns →_](/en/services/) [General FAQ_30+ fulfillment answers →_](/en/faq/) [What is Fulfillment_Complete guide for merchants →_](/en/what-is-fulfillment/)