MFG API v1
Connect your shop or ERP to MFG: request shipping quotes and follow shipments (Shipping module), and keep your catalogue and stock in MFG warehouses in sync (Stock module).
Getting started
- MFG activates the module(s) for your company. You see them in the portal, under Services.
- Your company manager creates keys in the portal, under API: a
testkey first, alivekey after the acceptance tests. - Send every request from your server to
https://api.mfgtradinggroup.com/v1withAuthorization: Bearer <key>. Never use the key in a browser or mobile app: the API refuses browser requests.
Conventions
- JSON in UTF-8, field names in
snake_case. Dates in ISO 8601 (UTC). Amounts in EUR as strings ("12.50"), excluding VAT. Weights in kg, dimensions in cm. Countries as ISO 3166-1 two-letter codes. - Errors:
{"error": {"code", "message", "request_id", "fields"}}. 400/422 invalid data · 401 invalid key · 403 missing permission, module disabled or IP not allowed · 404 not found (or not yours) · 409 state does not allow it · 429 too many requests (seeRetry-After) · 5xx retry later. - request_id: every response has
X-Request-Id. Quote it when asking support. - Idempotency: send
Idempotency-Keyon every POST. The same key with the same body within 24 h returns the same response (headerIdempotent-Replayed: true) and creates nothing new; with a different body you get422 idempotency_mismatch. - Lists: up to 100 items (
limit);nextis the cursor for the following page (?cursor=…).updated_sincereturns only what changed. - Limits: 120 requests per minute per key. Every response carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset(seconds); a429also carriesRetry-After. Repeated requests with an invalid key from the same IP are blocked for 15 minutes. - Test mode:
testkeys work on a separate test company with a test warehouse. Nothing reaches MFG warehouses, carriers or invoicing. Use the Test mode only endpoints to load stock and simulate what the warehouse does. - Prices are always the final price for your company. Carrier costs and MFG margins are never returned.
Automatic acceptance
Shipping prices change from day to day, so every request gets options with the price of the day. To ship without a manual step, send in the request (POST /orders or POST /quotes):
shipping:cheapestorfastest(the preferred option);max_price: the most you accept to pay, in EUR excluding VAT (for example what your shop charged the customer, plus a margin).
As soon as the options exist, the preferred one is accepted automatically if its price is at most max_price, and the order goes to the warehouse. If it costs more, the request stays quoted, the quote.quoted notification and the request carry above_max_price: true, and you decide: accept with /quotes/{id}/accept or cancel. Without max_price nothing is accepted automatically.
MFG can switch on automatic quoting for your company: requests (shipments from stock and shipments from your pickup address) are priced from the carriers within about a minute, instead of by a consultant. Together with max_price, a paid shop order is accepted without any manual step. The request goes to a consultant instead when no carrier returns a door-to-door price for that route, or when no automatic price fits your max_price; you are notified when the consultant sends the options. Your integration does not change when MFG adds carriers or countries: the same requests simply start being priced automatically.
The response and every read include auto_accept: {"service", "max_price", "above_max_price"}.
Checkout: live prices and pickup points
To let your customers choose the transport in your shop, with real prices:
- At checkout,
POST /rateswith the cart (warehouse and lines, or parcels) and the customer's country, postal code and city. Show the options (carrier, service, transit days, price). Use your fixed prices whendatais empty or the call fails. - When the customer picks an option with
pickup_point_required(home2shop: delivered to a shop or locker), callGET /pickup-pointswith itsrate_idand the customer's address, and let the customer choose a point. - When the order is paid,
POST /orders(orPOST /quotes) with therate_id, thepickup_pointandinsurance. The order is accepted at once at that price; you follow it with the usual notifications.
Service types: home2home (collected at origin, delivered to the address), home2shop (collected at origin, the customer collects at a pickup point), shop2home and shop2shop (the parcel is handed in at a carrier point at origin). A rate_id is valid for 24 hours, only for your company and key mode (live or test).
Insurance
Every shipment must say whether it is insured: insurance: true or false. Ask your customer at checkout, as airlines do. Without an answer, /quotes/{id}/accept returns 422, and a request with max_price (automatic acceptance) is refused at creation.
- Price, by the value of the goods (
customs_value, EUR): up to 200 → 5.00; up to 1000 → 10.00; up to 2000 → 20.00; above 2000 → 1% of the value (3000 → 30.00). Excluding VAT, invoiced on a separate line. - With
insurance: true,customs_valueis required. For orders from stock it can be left out when every product has aunit_value(value × quantity). max_pricecompares the transport price only; the insurance is added on top.- Covers loss or damage in transit only. Not covered: goods prohibited or restricted by the carriers, and goods not packed properly (strong box, filling, secure closing).
Every read includes insurance: {"selected", "price"}: selected is null until answered; price is the price charged (or what it would cost with the current customs_value).
Checkout
POST /rates · shipping:read or stock:read
Live prices for your checkout, without creating a request: one option per service type and speed (cheapest and fastest), final price in EUR excluding VAT, with your conditions. Origin: warehouse (with lines or parcels) or origin (address_id or address). destination needs country, postal_code and city (address1 is needed later for pickup points). service_types (optional): home2home, home2shop, shop2home, shop2shop. Answers within about 8 seconds; complete=false when a carrier did not answer in time (show your fixed prices if data is empty). The same cart is cached for 10 minutes. Each option has a rate_id valid for 24 hours and pickup_point_required. With a test key the prices are fictitious.
{
"warehouse": "Bergamo",
"lines": [
{
"sku": "CR-050",
"quantity": 2
}
],
"destination": {
"country": "PT",
"postal_code": "1100-053",
"city": "Lisboa",
"address1": "Rua Augusta 100"
},
"service_types": [
"home2home",
"home2shop"
]
}
GET /pickup-points · shipping:read or stock:read
Pickup points (shops, lockers) near the customer for a rate with pickup_point_required, closest first. Query: rate_id, country, postal_code, city, address1. Each point: code, name, address, latitude, longitude, opening_hours. Send the chosen code as pickup_point.code with the order.
POST /orders · stock:write
Order from stock with the service chosen at checkout: send the rate_id (and pickup_point when the rate needs it). The order is accepted at once at that price and goes to the warehouse. insurance (true or false) and recipient name and phone are required. The rate_id must be for the same warehouse, the same destination country and postal code, and at most 10% more weight; otherwise 422 rate_mismatch (ask for new rates). The same works for POST /quotes from a pickup address.
{
"client_reference": "SHOP-10484",
"warehouse": "Bergamo",
"lines": [
{
"sku": "CR-050",
"quantity": 2
}
],
"rate_id": "<rate_id from POST /rates>",
"pickup_point": {
"code": "13#PT20524",
"name": "City Lockers Chiado"
},
"insurance": false,
"destination": {
"address1": "Rua Augusta 100",
"postal_code": "1100-053",
"city": "Lisboa",
"country": "PT"
},
"recipient": {
"name": "Maria Silva",
"phone": "+351 910 000 000",
"email": "maria@example.com"
}
}
Shipping
POST /quotes · shipping:write
Create a quote request (from a saved pickup address or a full origin address). All parcels up to 30 kg. Optional automatic acceptance: shipping (cheapest or fastest) and max_price (EUR, excl. VAT) - see Automatic acceptance. With a test key, two fictitious options (12.50 and 24.90 EUR) arrive at once. With a rate_id (see Checkout), the request is accepted at once at that price.
{
"client_reference": "SHOP-10482",
"origin": {
"address_id": "0b6a8c1e-1d2f-4c3b-9a8e-2f1d0c9b8a7e"
},
"destination": {
"company": "Loja Centro",
"address1": "Rua Augusta 100",
"postal_code": "1100-053",
"city": "Lisboa",
"country": "PT"
},
"recipient": {
"name": "Maria Silva",
"phone": "+351 910 000 000",
"email": "maria@example.com"
},
"parcels": [
{
"quantity": 2,
"weight_kg": "4.5",
"length_cm": 40,
"width_cm": 30,
"height_cm": 20
}
],
"contents": "Cosmetics",
"customs_value": "180.00",
"desired_date": "2026-11-20",
"shipping": "cheapest",
"max_price": "9.50",
"insurance": true
}
GET /quotes · shipping:read
List requests. Filters: status (received, quoted, accepted, declined, expired, cancelled), updated_since, type=shipping. Paginated.
GET /quotes/{id} · shipping:read
One request with its options (carrier, service, transit days, final price in EUR excluding VAT, valid_until) and its shipment.
POST /quotes/{id}/accept · shipping:write
Accept an option (also for orders). recipient.name and recipient.phone are required (sent now or in the request). A new recipient replaces the previous one. insurance (true or false) is required unless it was sent in the request; with true, customs_value is required (now or in the request) - see Insurance.
{
"option_id": 812,
"insurance": true,
"customs_value": "180.00",
"recipient": {
"name": "Maria Silva",
"phone": "+351 910 000 000"
}
}
POST /quotes/{id}/decline · shipping:write
Decline the options. reason: price, transit, provider, not_needed or other; note is optional.
{
"reason": "price",
"note": "Found a cheaper option."
}
POST /quotes/{id}/cancel · shipping:write
reason is required. Before acceptance: cancelled at once (200). After acceptance: cancellation requested (202); MFG decides and you receive quote.cancel_decided. With a test key the request is decided at once (free).
{
"reason": "Customer cancelled the order."
}
POST /quotes/{id}/erase · shipping:write
Erase the recipient's personal data (name, address, phone, email, notes, waybill) once the shipment is delivered or the request is closed; before that, 409 not_closed. Kept: your client_reference, the MFG reference, city, country, the first characters of the postal code, parcels, carrier and tracking. MFG does this automatically after the period in your data processing agreement (90 days after delivery by default). personal_data_erased_at shows when.
GET /shipments/{id} · shipping:read
Shipment status, tracking number and events. The shipment id is the quote id.
GET /shipments/{id}/waybill · shipping:read
The waybill PDF, only with your key, once available.
GET /addresses · shipping:read
Pickup and delivery addresses saved in the portal (pickup=true for pickup addresses).
Stock
PUT /products/{sku} · stock:write
Create or update a product by SKU.
{
"name": "Face cream 50 ml",
"barcode": "5601234567890",
"unit_weight_kg": "0.120",
"length_cm": "6",
"width_cm": "6",
"height_cm": "8",
"hs_code": "330499",
"origin_country": "IT",
"unit_value": "9.90",
"track_lot": true,
"track_expiry": true,
"min_stock": 50
}
POST /products/batch · stock:write
Create or update up to 500 products. All or nothing: if one is invalid, nothing is saved.
{
"products": [
{
"sku": "CR-050",
"name": "Face cream 50 ml"
}
]
}
GET /products · stock:read
List the catalogue. Paginated. has_image tells whether the product has an image.
PUT /products/{sku}/image · stock:write
Set the product image, printed on the warehouse picking list. Send the image bytes as the body (not JSON), with Content-Type image/jpeg, image/png, image/webp or image/gif, up to 5 MB. MFG keeps only a 400 px JPEG copy. Example: curl -X PUT --data-binary @cream.jpg -H "Content-Type: image/jpeg" .../v1/products/CR-050/image
GET /products/{sku}/image · stock:read
The stored image (JPEG).
DELETE /products/{sku}/image · stock:write
Remove the product image.
GET /stock · stock:read
Stock per product and warehouse: on_hand (sellable), reserved, available (on_hand minus reserved) and unsellable (returns kept apart, never reserved or shipped), and per lot, expiry and serial with a sellable flag. Filters: sku, warehouse, updated_since. Kits are not known to MFG: send components.
GET /movements · stock:read
Receipts, dispatches, transfers, adjustments and return_unsellable (a returned item that stays unsellable), in order, each with a sellable flag. Filters: since, sku. Use the cursor to read new movements.
POST /inbounds · stock:write
Announce goods arriving at a warehouse (also used for the initial inventory). The warehouse receives it with the lines already filled in and confirms the counted quantities, lots and expiry dates. Up to 200 lines per request (inbounds, orders and returns).
{
"warehouse": "Bergamo",
"expected_date": "2026-11-25",
"client_reference": "PO-2211",
"lines": [
{
"sku": "CR-050",
"quantity": 200
}
]
}
GET /inbounds/{id} · stock:read
Status and what was counted on arrival (lots, expiry, serials).
POST /orders · stock:write
Ship from stock. Reserves the items (earliest expiry first) and creates the shipping request. Without enough stock: 409 insufficient_stock. Parcels are optional (estimated from product weight and dimensions; send them for accurate prices). shipping (default cheapest) and max_price enable automatic acceptance. shipping "own" (optional carrier name): your own carrier collects at the warehouse, no MFG quote or transport price; the order is accepted at once and waits for your label (POST /orders/{id}/label).
{
"client_reference": "SHOP-10483",
"warehouse": "Bergamo",
"shipping": "cheapest",
"max_price": "8.80",
"insurance": false,
"lines": [
{
"sku": "CR-050",
"quantity": 3
},
{
"sku": "SR-200",
"quantity": 1
}
],
"destination": {
"address1": "Kurfürstendamm 21",
"postal_code": "10719",
"city": "Berlin",
"country": "DE"
},
"recipient": {
"name": "Jonas Weber",
"phone": "+49 30 000000"
}
}
POST /orders/{id}/label · stock:write
Only for orders with shipping "own" (your own carrier, no MFG transport): send the carrier label as a base64 PDF (up to 5 MB) and, if known, the tracking number. The warehouse prints it, sticks it on and records the dispatch (handed to your carrier); without a label the order is prepared but does not leave. The label can be replaced until the order leaves.
{
"pdf": "<base64 of the PDF>",
"tracking_number": "BR123456789",
"carrier": "Transportadora BR"
}
GET /orders/{id} · stock:read
Order status: received, quoted, accepted, shipped (left the warehouse), delivered, cancelled. After it leaves: shipped_at and, per line, the lots, expiry dates and serial numbers shipped.
POST /orders/{id}/cancel · stock:write
reason is required. Cancel while the order has not left the warehouse; after that, 409 already_prepared. Once accepted, it is a request (202) that MFG decides (quote.cancel_decided, then order.cancelled); with a test key it is decided at once.
{
"reason": "Customer cancelled."
}
POST /orders/{id}/erase · stock:write
Erase the recipient's personal data of a delivered or closed order. Same rules as POST /quotes/{id}/erase.
POST /returns · stock:write
Announce a return. restock=false asks for the item to stay unsellable.
{
"warehouse": "Bergamo",
"client_reference": "RMA-77",
"lines": [
{
"sku": "CR-050",
"quantity": 2,
"reason": "damaged box",
"restock": false
}
]
}
GET /returns/{id} · stock:read
What arrived, what went back to sellable stock and what stays unsellable (outside stock).
Test mode only
POST /test/stock · stock:write
Load fictitious stock in the test warehouse. DELETE empties it.
{
"sku": "CR-050",
"quantity": 20,
"lot": "L1",
"expiry": "2027-06-30"
}
POST /test/inbounds/{id}/receive · stock:write
Simulate the warehouse receiving an inbound.
POST /test/orders/{id}/ship · stock:write
Simulate the dispatch of an accepted test order.
POST /test/returns/{id}/receive · stock:write
Simulate the return check; optional lines with restocked_quantity.
POST /test/shipments/{id}/advance · shipping:write
Move a test shipment to the next status.
Personal data
MFG processes your recipients' data only to carry out your shipments, under the data processing agreement you sign in the portal (Contracts). After the agreed period (90 days after delivery by default), the recipient's name, address, phone, email, notes and the waybill are erased automatically; the order keeps your client_reference, city, country, the first characters of the postal code, parcels, carrier and tracking, so you can still match it in your system. Use POST /quotes/{id}/erase or POST /orders/{id}/erase to erase earlier, for example when a recipient asks. Live API keys can only be created once the required contracts are signed.
Webhooks
Set an HTTPS address in the portal (one for test, one for live). MFG sends a POST with {"event_id", "type", "created_at", "data"}. Answer 2xx within 10 seconds; otherwise MFG retries after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h. The portal lists every notification with a Resend button.
- Only public HTTPS host names are accepted; redirects are not followed.
- Events can arrive more than once and out of order: ignore repeated
event_ids and, before acting, read the object with itsGET. - Header
MFG-Signature: t=<unix time>,v1=<hmac>: HMAC-SHA256 of<t>.<body>with your secret. During a secret rotation (24 h) there are twov1values: one match is enough.
| Event | When |
|---|---|
quote.quoted | MFG sent options. |
quote.expired | Options expired without an answer. |
quote.cancel_decided | MFG decided a cancellation request (free, charged or refused). |
shipment.status_changed | Ready, in transit, delivered or problem. |
shipment.waybill_ready | The waybill can be downloaded. |
inbound.received | The warehouse counted an inbound. |
return.received | The warehouse checked a return. |
stock.changed | Stock moved for a product (sku). |
stock.low | A product went below its minimum. |
order.shipped | An order left the warehouse, with lots and serial numbers. |
order.cancelled | An order was cancelled and its reservation released. |
Verifying the signature (Python)
import hashlib, hmac, time
def verify(body: bytes, header: str, secrets: list[str]) -> bool:
parts = [p.split("=", 1) for p in header.split(",")]
t = int(next(v for k, v in parts if k == "t"))
if abs(time.time() - t) > 300:
return False # older than 5 minutes
signatures = [v for k, v in parts if k == "v1"]
for secret in secrets: # during a rotation: old and new secret
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
if any(hmac.compare_digest(expected, s) for s in signatures):
return True # one match is enough
return False