提报订单

POST/channel/api/v1/order/submit

Auth: request-token (channel_partner)

以认证渠道伙伴的身份提报订单。shop_id 必须属于该伙伴绑定的店铺；超出范围的店铺会被拒绝，且不会创建任何订单。

某个产品/变体（以 shop_sku 标识）首次提报时，平台会用你在此处提交的字段创建商品目录记录，因此请尽量完整地提供产品与变体信息。

字段边界

本接口在两个方向都有明确边界：

请求边界（可传入什么）。 仅接受本页记录的字段，其他字段（尤其是内部标识或平台托管值）会被忽略。请勿传入平台 id（id、sku_id、product_id、shop_sku_id、catalog_id、order_id）、订单状态、结算/账单字段，以及内部成本字段（cost、cost_price、employee_price）。成本与内部利润数据永远不会从渠道伙伴侧接收。
响应边界（能拿到什么）。 提报响应仅返回 code、msg 与 data.order_id，绝不返回内部成本、利润、结算、员工或目录内部字段。任何读取类接口返回的价格也仅限渠道伙伴被允许查看的范围。

传入未允许的字段不会报错，会被静默丢弃。请勿依赖本页未记录的任何字段。

请求头

头	必填	说明
`request-token`	是	渠道伙伴应用 token
`Content-Type`	是	`application/json`

请求体

字段	类型	必填	说明
`shop_id`	integer	是	绑定的店铺 id
`shop_order_no`	string	是	店铺内唯一订单号。与 `shop_id` 共同作为幂等键
`shipping_standard`	string	是	与 e2c-energy 约定的配送标准/服务编码
`payment_method`	string	是	支付方式标识（如 `bank_transfer`）
`purchase_time`	string	是	下单时间 `YYYY-MM-DD HH:mm:ss`（店铺本地时间）
`billing_address`	object	是	账单地址 — 见地址对象
`shipping_address`	object	是	收货地址 — 见地址对象
`order_item`	array<object>	是	订单明细行 — 见订单明细对象
`order_amount`	array<object>	是	费用/金额行 — 见订单金额对象

地址对象

billing_address 与 shipping_address 共用此结构。

字段	类型	必填	说明
`full_name`	string	是	收件人/付款人全名
`country_code`	string	是	ISO 3166-1 alpha-2 国家代码（如 `DE`、`NL`、`FR`）
`province`	string	是	省/州/地区
`city`	string	是	城市
`address1`	string	是	街道地址第一行
`address2`	string	否	街道地址第二行
`address3`	string	否	街道地址第三行
`suburbs`	string	否	郊区/区
`postcode`	string	否	邮政编码
`tel`	string	否	联系电话
`email`	string	否	联系邮箱
`company`	string	否	公司名称
`tax_id`	string	否	税号/VAT 号（B2B 开票建议提供）
`kvk_number`	string	否	商会注册号（荷兰 KvK），如适用

订单明细对象

order_item 数组中的每一项。

字段	类型	必填	说明
`quantity`	integer	是	订购数量
`price`	number	是	该明细行实际收取的单价，以订单币种计
`shop_order_item_primary_key`	string	否	你自己的明细行 id，用于对账回传
`item`	object	是	产品详情 — 见产品对象

产品对象

每个订单明细的 item 字段。首次同步时（以 shop_id + shop_sku 判定）用这些字段创建产品；之后同步复用已有产品。

字段	类型	必填	说明
`title`	string	是	产品标题
`shop_sku`	string	是	店铺内产品级 SKU（产品身份标识）
`sale_price`	number	是	产品销售价（小数，2 位）
`weight`	number	是	产品重量（小数，2 位）
`weight_unit`	string	是	重量单位，如 `kg`（默认）或 `g`
`images`	object	是	按选项值分组的图片对象 — 见产品图片与变体选项
`primary_image_key`	string	是	`standard` 中用于选图的选项名 — 见产品图片与变体选项
`variant`	object	是	变体详情 — 见变体对象
`description`	string	否	产品描述
`mpn`	string	否	制造商零件号
`ean`	string	否	EAN/条码
`condition`	string	否	商品成色，默认 `new`
`price`	number	否	折前标价
`suggest_price`	number	否	建议零售价
`length`	number	否	长（小数）
`width`	number	否	宽（小数）
`height`	number	否	高（小数）
`length_unit`	string	否	长度单位，默认 `cm`
`mqq`	integer	否	最小起订量，默认 `1`
`step`	integer	否	订购数量步长，默认 `1`
`highlights`	string	否	卖点/亮点
`video`	string	否	产品视频 key 或 URL

变体对象

产品对象的 variant 字段。身份标识为 shop_sku（变体级）。

字段	类型	必填	说明
`shop_sku`	string	是	店铺内变体级 SKU（变体身份标识）
`standard`	object	是	变体选项的键值映射 — 见产品图片与变体选项
`sale_price`	number	是	变体销售价（小数，2 位）
`weight`	number	是	变体重量（小数，2 位）
`weight_unit`	string	是	变体重量单位，如 `kg`（默认）或 `g`
`sku`	string	否	你的内部 SKU；提供时用于匹配主目录
`ean`	string	否	EAN/条码
`price`	number	否	变体折前标价
`suggest_price`	number	否	变体建议价
`length`	number	否	长（小数）
`width`	number	否	宽（小数）
`height`	number	否	高（小数）
`length_unit`	string	否	长度单位，默认 `cm`
`unit`	string	否	销售单位标签
`hs_code`	string	否	HS 海关编码（跨境建议提供）
`mqq`	integer	否	最小起订量，默认 `1`
`step`	integer	否	订购数量步长，默认 `1`
`dg`	boolean	否	危险品标志，默认 `false`
`dg_standard`	string	否	危险品标准，`dg` 为 true 时提供

产品图片与变体选项

standard、primary_image_key、images 三者协同描述变体选项并把每个变体映射到对应图片。它们是结构化 JSON，而非扁平字符串。

standard（变体对象） — 选项名 → 选项值的键值映射。key 是你的选项维度，value 是该变体的取值：

json

{ "color": "black", "size": "500W" }

无真实选项的产品可用单一合成选项，如 { "id": "3241" }。

primary_image_key（产品对象） — standard 中用于选图的选项名（不是图片 key）。通常为 color（每种颜色一组图），单变体产品用 id。

images（产品对象） — JSON 对象，key 为 primary_image_key 对应选项的各个取值，value 为该取值的图片 URL 数组：

json

{
  "black": ["https://cdn.example.com/pps500-black-1.jpg", "https://cdn.example.com/pps500-black-2.jpg"],
  "white": ["https://cdn.example.com/pps500-white-1.jpg"]
}

解析方式。 对某个变体，平台读取 images[ standard[primary_image_key] ] 得到该变体图片。上例中若 primary_image_key = "color"、变体 standard.color = "black"，其图片即 black 数组。若变体选项值在 images 中不存在，则回退使用第一组图片。

规则

变体中出现的 primary_image_key 选项的每个不同取值，都应在 images 中有对应 key。
图片项必须是完整、可公开访问的 URL。
单变体产品：primary_image_key: "id"，standard: { "id": "<任意稳定值>" }，并用同一值作为 images 的 key，如 { "<value>": ["https://.../main.jpg"] }。

订单金额对象

order_amount 数组中的每一项，表示订单的一条费用/金额行。请提供构成订单总额的各行；fee_code 标识行类型，用于在单个订单内对费用行去重。

字段	类型	必填	说明
`subject`	string	是	该费用行的可读描述
`amount`	number	是	金额，小数（2 位），必须 `>= 0.01`
`currency`	string	是	ISO 4217 货币代码，如 `EUR`
`fee_code`	string	建议	费用行类型 — 见下表

平台使用的 fee_code 取值：

`fee_code`	含义	示例 subject
`sub_total`	商品小计（各行价格之和）	`Product Total`
`discount_fee`	订单级折扣（在折扣行上以正数金额表示）	`Discount`
`actual_shipping`	实际收取的运费	`Actual Shipping Fee`
`adjust_shipping`	运费调整	`Adjust Shipping Fee`
`tax`	税费/VAT	`Tax`
`pay_commission`	支付/结算佣金	`Settlement Fee`
`return_fee`	退货相关费用	`Return Fee`

至少提供 sub_total、tax，以及（如适用）运费行 actual_shipping；其余编码可选。

cURL

curl -X POST 'https://apigate.e2c-energy.com/channel/api/v1/order/submit' \
  -H 'request-token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "shop_id": 123,
  "shop_order_no": "SO-1001",
  "shipping_standard": "STD",
  "payment_method": "bank_transfer",
  "purchase_time": "2026-07-22 10:00:00",
  "billing_address": {
    "full_name": "John Doe",
    "company": "Doe GmbH",
    "tax_id": "DE123456789",
    "country_code": "DE",
    "province": "Bavaria",
    "city": "Munich",
    "address1": "Marienplatz 1",
    "postcode": "80331",
    "tel": "+49 89 000000",
    "email": "john@doe.example"
  },
  "shipping_address": {
    "full_name": "John Doe",
    "country_code": "DE",
    "province": "Bavaria",
    "city": "Munich",
    "address1": "Marienplatz 1",
    "postcode": "80331",
    "tel": "+49 89 000000"
  },
  "order_item": [
    {
      "quantity": 2,
      "price": 49.9,
      "shop_order_item_primary_key": "LINE-1",
      "item": {
        "title": "Portable Power Station",
        "shop_sku": "PPS-500",
        "sale_price": 49.9,
        "weight": 5.2,
        "weight_unit": "kg",
        "images": {
          "black": [
            "https://cdn.example.com/pps500-black-1.jpg",
            "https://cdn.example.com/pps500-black-2.jpg"
          ]
        },
        "primary_image_key": "color",
        "mpn": "PPS500",
        "ean": "4006381333931",
        "variant": {
          "shop_sku": "PPS-500-BLK",
          "sku": "PPS-500-BLK",
          "standard": {
            "color": "black",
            "size": "500W"
          },
          "sale_price": 49.9,
          "weight": 5.2,
          "weight_unit": "kg",
          "hs_code": "8507600000"
        }
      }
    }
  ],
  "order_amount": [
    {
      "subject": "Product Total",
      "amount": 99.8,
      "currency": "EUR",
      "fee_code": "sub_total"
    },
    {
      "subject": "Actual Shipping Fee",
      "amount": 9.9,
      "currency": "EUR",
      "fee_code": "actual_shipping"
    },
    {
      "subject": "Tax",
      "amount": 20.94,
      "currency": "EUR",
      "fee_code": "tax"
    }
  ]
}'

响应

json

{ "code": 200, "msg": "order submit succeed", "data": { "order_id": 456 } }

错误码

code	含义
909	token 缺失/无效、应用已停用，或类型不是 `channel_partner`
400	店铺未绑定到该渠道伙伴，或请求校验失败

幂等性

短时间内重复提报相同的 shop_id + shop_order_no 会被去重：返回已存在的订单，而非创建重复订单。

提报订单 ​

字段边界 ​

请求头 ​

请求体 ​

地址对象 ​

订单明细对象 ​

产品对象 ​

变体对象 ​

产品图片与变体选项 ​

订单金额对象 ​

cURL ​

响应 ​

错误码 ​

幂等性 ​

提报订单

字段边界

请求头

请求体

地址对象

订单明细对象

产品对象

变体对象

产品图片与变体选项

订单金额对象

cURL

响应

错误码

幂等性