B2B 文档

B2B API——自动获取订单和产品信息

我们的 REST API 向每位拥有客户账户的客户开放，可自动获取订单和产品信息并集成到自己的系统中。

身份验证

所有 API 请求都需要一个有效的 API-Key，并随 HTTP 标头一同发送。API 访问与您的客户账户绑定，原则上向客户账户开放。

info 您无需单独的 B2B 申请：使用您的客户账户登录，打开 API 选项卡，并在那里生成您的 API-Key。前往 API 访问 →

标头格式

HTTP Request Header

X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

使用 cURL 的示例

cURL

curl -X GET "https://artumos.com/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Base URL

所有端点都相对于以下 Base URL：

Base URL

https://artumos.com/api/v1

所有响应均以 JSON 形式返回 (Content-Type: application/json).

Rate Limits

Plan	请求 / 分钟	请求 / 天
客户账户	60	5.000
扩展限额	按需	按需

超出限额时将返回 HTTP 429 Too Many Requests 。标头 Retry-After 包含以秒为单位的等待时间。

错误代码

HTTP-Code	含义
`200 OK`	请求成功
`400 Bad Request`	无效参数
`401 Unauthorized`	缺少或无效的 API-Key
`403 Forbidden`	无权访问此资源
`404 Not Found`	未找到资源
`429 Too Many Requests`	超出 Rate Limit
`500 Internal Server Error`	服务器错误——请联系支持

错误响应格式

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

端点：订单

GET /api/v1/orders 账户的所有订单

Parameter	类型	描述
`page`	integer	页码（默认：1）
`per_page`	integer	每页条目数（最多 100）
`status`	string	`paid` \| `pending` \| `all`

Beispiel-Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ORD-12345",
        "status": "paid",
        "total": 49.99,
        "currency": "EUR",
        "created_at": "2026-01-15T10:30:00Z",
        "items_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 42
    }
  }
}

GET /api/v1/orders/{order_id} 获取单个订单

端点：产品和订单信息

GET /api/v1/orders/{order_id}/codes 一个订单的所有产品信息

Beispiel-Response

{
  "success": true,
  "data": {
    "order_id": "ORD-12345",
    "codes": [
      {
        "id": "CODE-789",
        "product_name": "Beispielprodukt vom Marktplatz",
        "product_sku": "ART-PRODUCT-001",
        "product_info": "Hinweise laut Verkäuferangaben",
        "delivery_url": "https://...",
        "delivered_at": "2026-01-15T10:31:00Z",
        "status": "active"
      }
    ]
  }
}

GET /api/v1/codes/{code_id} 获取单条产品信息

warning 产品和订单信息只能在相应订单和卖家信息的范围内使用。滥用转发可能违反使用条款。

端点：产品

GET /api/v1/products 获取产品目录

Parameter	类型	描述
`category`	string	按类别标识符筛选
`in_stock`	boolean	仅可供应的产品
`page`	integer	页码

Beispiel-Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": 42,
        "sku": "ART-PRODUCT-001",
        "name": "Beispielprodukt vom Marktplatz",
        "price": 49.99,
        "currency": "EUR",
        "in_stock": true,
        "category": "handmade"
      }
    ]
  }
}

Webhooks

Webhook 让您能够在提供订单或代码时接收实时通知。Webhook URL 可在客户账户中设置。

可用事件

Event	描述
`order.paid`	订单已支付
`codes.delivered`	代码已提供
`order.refunded`	订单已退款

Webhook Payload

POST – 您的 Webhook 端点

{
  "event": "codes.delivered",
  "timestamp": "2026-01-15T10:31:05Z",
  "data": {
    "order_id": "ORD-12345",
    "codes_count": 2
  },
  "signature": "sha256=..."
}

使用您的 Webhook Secret 验证签名： HMAC-SHA256(payload, webhook_secret)

常见问题

谁可以使用 B2B API？

每位拥有客户账户的客户都可以使用 API 访问。登录您的客户账户，并使用相应的 API-Key 进行经过身份验证的请求。

响应是什么格式？

所有响应均以 JSON 形式返回。Root 对象始终包含 success: true/false 以及 data 或 error.

我可以通过 API 下订单吗？

在第一个版本中，API 用于获取订单、订单和产品信息。写入型订单端点将在可用时单独开放。

是否有 Sandbox 环境？

是的。Sandbox 可在客户账户的「API 访问」选项卡中激活，并直接与相应的 API-Key 绑定。