{
  "openapi": "3.0.3",
  "info": {
    "title": "MFG API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.mfgtradinggroup.com/v1"
    }
  ],
  "paths": {
    "/rates": {
      "post": {
        "summary": "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.",
        "tags": [
          "Checkout"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read or stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "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"
                ]
              }
            }
          }
        }
      }
    },
    "/pickup-points": {
      "get": {
        "summary": "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.",
        "tags": [
          "Checkout"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read or stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        }
      }
    },
    "/orders": {
      "post": {
        "summary": "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).",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "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"
                }
              }
            }
          }
        }
      }
    },
    "/quotes": {
      "post": {
        "summary": "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.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "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": {
        "summary": "List requests. Filters: status (received, quoted, accepted, declined, expired, cancelled), updated_since, type=shipping. Paginated.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        }
      }
    },
    "/quotes/{id}": {
      "get": {
        "summary": "One request with its options (carrier, service, transit days, final price in EUR excluding VAT, valid_until) and its shipment.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/accept": {
      "post": {
        "summary": "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.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "option_id": 812,
                "insurance": true,
                "customs_value": "180.00",
                "recipient": {
                  "name": "Maria Silva",
                  "phone": "+351 910 000 000"
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{id}/decline": {
      "post": {
        "summary": "Decline the options. reason: price, transit, provider, not_needed or other; note is optional.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "reason": "price",
                "note": "Found a cheaper option."
              }
            }
          }
        }
      }
    },
    "/quotes/{id}/cancel": {
      "post": {
        "summary": "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).",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "reason": "Customer cancelled the order."
              }
            }
          }
        }
      }
    },
    "/quotes/{id}/erase": {
      "post": {
        "summary": "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.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/shipments/{id}": {
      "get": {
        "summary": "Shipment status, tracking number and events. The shipment id is the quote id.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/shipments/{id}/waybill": {
      "get": {
        "summary": "The waybill PDF, only with your key, once available.",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/addresses": {
      "get": {
        "summary": "Pickup and delivery addresses saved in the portal (pickup=true for pickup addresses).",
        "tags": [
          "Shipping"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        }
      }
    },
    "/products/{sku}": {
      "put": {
        "summary": "Create or update a product by SKU.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "sku",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "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
              }
            }
          }
        }
      }
    },
    "/products/batch": {
      "post": {
        "summary": "Create or update up to 500 products. All or nothing: if one is invalid, nothing is saved.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "products": [
                  {
                    "sku": "CR-050",
                    "name": "Face cream 50 ml"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/products": {
      "get": {
        "summary": "List the catalogue. Paginated. has_image tells whether the product has an image.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        }
      }
    },
    "/products/{sku}/image": {
      "put": {
        "summary": "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",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "sku",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "get": {
        "summary": "The stored image (JPEG).",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "sku",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "delete": {
        "summary": "Remove the product image.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "sku",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/stock": {
      "get": {
        "summary": "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.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        }
      }
    },
    "/movements": {
      "get": {
        "summary": "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.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        }
      }
    },
    "/inbounds": {
      "post": {
        "summary": "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).",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "warehouse": "Bergamo",
                "expected_date": "2026-11-25",
                "client_reference": "PO-2211",
                "lines": [
                  {
                    "sku": "CR-050",
                    "quantity": 200
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/inbounds/{id}": {
      "get": {
        "summary": "Status and what was counted on arrival (lots, expiry, serials).",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/orders/{id}/label": {
      "post": {
        "summary": "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.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "pdf": "<base64 of the PDF>",
                "tracking_number": "BR123456789",
                "carrier": "Transportadora BR"
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "summary": "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.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/orders/{id}/cancel": {
      "post": {
        "summary": "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.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "reason": "Customer cancelled."
              }
            }
          }
        }
      }
    },
    "/orders/{id}/erase": {
      "post": {
        "summary": "Erase the recipient's personal data of a delivered or closed order. Same rules as POST /quotes/{id}/erase.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/returns": {
      "post": {
        "summary": "Announce a return. restock=false asks for the item to stay unsellable.",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "warehouse": "Bergamo",
                "client_reference": "RMA-77",
                "lines": [
                  {
                    "sku": "CR-050",
                    "quantity": 2,
                    "reason": "damaged box",
                    "restock": false
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/returns/{id}": {
      "get": {
        "summary": "What arrived, what went back to sellable stock and what stays unsellable (outside stock).",
        "tags": [
          "Stock"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:read",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/test/stock": {
      "post": {
        "summary": "Load fictitious stock in the test warehouse. DELETE empties it.",
        "tags": [
          "Test mode only"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "sku": "CR-050",
                "quantity": 20,
                "lot": "L1",
                "expiry": "2027-06-30"
              }
            }
          }
        }
      }
    },
    "/test/inbounds/{id}/receive": {
      "post": {
        "summary": "Simulate the warehouse receiving an inbound.",
        "tags": [
          "Test mode only"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/test/orders/{id}/ship": {
      "post": {
        "summary": "Simulate the dispatch of an accepted test order.",
        "tags": [
          "Test mode only"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/test/returns/{id}/receive": {
      "post": {
        "summary": "Simulate the return check; optional lines with restocked_quantity.",
        "tags": [
          "Test mode only"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "stock:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/test/shipments/{id}/advance": {
      "post": {
        "summary": "Move a test shipment to the next status.",
        "tags": [
          "Test mode only"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "x-permission": "shipping:write",
        "responses": {
          "default": {
            "description": "See the documentation."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}