B2B API – Truy xuất tự động thông tin đơn hàng và sản phẩm
REST-API của chúng tôi dành cho mọi khách hàng có tài khoản khách hàng và cho phép truy xuất tự động thông tin đơn hàng và sản phẩm cũng như tích hợp vào hệ thống riêng.
Xác thực
Tất cả các yêu cầu API đều cần một API-Key hợp lệ được gửi kèm trong HTTP-Header. Quyền truy cập API được gắn với tài khoản khách hàng của bạn và về cơ bản dành cho các tài khoản khách hàng.
Định dạng Header
X-API-Key: YOUR_API_KEY_HERE Content-Type: application/json Accept: application/json
Ví dụ với cURL
curl -X GET "https://artumos.com/api/v1/orders" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "Accept: application/json"
Base URL
Tất cả các Endpoint đều tương đối so với Base URL sau:
https://artumos.com/api/v1
Tất cả các phản hồi được trả về dưới dạng JSON trả về (Content-Type: application/json).
Rate Limits
| Plan | Yêu cầu / Phút | Yêu cầu / Ngày |
|---|---|---|
| Tài khoản khách hàng | 60 | 5.000 |
| Giới hạn mở rộng | theo yêu cầu | theo yêu cầu |
Khi vượt quá sẽ HTTP 429 Too Many Requests trả về. Header Retry-After chứa thời gian chờ tính bằng giây.
Mã lỗi
| HTTP-Code | Ý nghĩa |
|---|---|
200 OK | Yêu cầu thành công |
400 Bad Request | Tham số không hợp lệ |
401 Unauthorized | Thiếu hoặc không hợp lệ API-Key |
403 Forbidden | Không có quyền với tài nguyên này |
404 Not Found | Không tìm thấy tài nguyên |
429 Too Many Requests | Đã vượt quá Rate Limit |
500 Internal Server Error | Lỗi máy chủ – vui lòng liên hệ hỗ trợ |
Định dạng Fehler-Response
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key."
}
}
Endpoint: Đơn hàng
/api/v1/orders
Tất cả đơn hàng của tài khoản
| Parameter | Loại | Mô tả |
|---|---|---|
page | integer | Trang (mặc định: 1) |
per_page | integer | Mục trên mỗi trang (tối đa 100) |
status | string | paid | pending | all |
{
"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
}
}
}
/api/v1/orders/{order_id}
Truy xuất một đơn hàng riêng lẻ
Endpoint: Thông tin sản phẩm và đơn hàng
/api/v1/orders/{order_id}/codes
Tất cả thông tin sản phẩm của một đơn hàng
{
"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"
}
]
}
}
/api/v1/codes/{code_id}
Truy xuất một thông tin sản phẩm riêng lẻ
Endpoint: Sản phẩm
/api/v1/products
Truy xuất danh mục sản phẩm
| Parameter | Loại | Mô tả |
|---|---|---|
category | string | Lọc theo Kategorie-Slug |
in_stock | boolean | Chỉ các sản phẩm có sẵn |
page | integer | Trang |
{
"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 cho phép nhận thông báo thời gian thực khi đơn hàng hoặc mã được cung cấp. Webhook-URL có thể được lưu trong tài khoản khách hàng.
Các Event có sẵn
| Event | Mô tả |
|---|---|
order.paid | Đơn hàng đã được thanh toán |
codes.delivered | Các mã đã được cung cấp |
order.refunded | Đơn hàng đã được hoàn tiền |
Webhook Payload
{
"event": "codes.delivered",
"timestamp": "2026-01-15T10:31:05Z",
"data": {
"order_id": "ORD-12345",
"codes_count": 2
},
"signature": "sha256=..."
}
Hãy xác minh chữ ký bằng Webhook-Secret của bạn: HMAC-SHA256(payload, webhook_secret)
Câu hỏi thường gặp
Mọi khách hàng có tài khoản khách hàng đều có thể sử dụng quyền truy cập API. Hãy đăng nhập vào tài khoản khách hàng của bạn và sử dụng API-Key tương ứng cho các yêu cầu đã được xác thực.
Tất cả các phản hồi được trả về dưới dạng JSON. Đối tượng Root luôn chứa success: true/false cũng như hoặc là data hoặc error.
Trong phiên bản đầu tiên, API phục vụ việc truy xuất đơn hàng, thông tin đơn hàng và sản phẩm. Các Endpoint ghi đơn hàng sẽ được mở riêng ngay khi chúng có sẵn.
Có. Sandbox có thể được kích hoạt trong tài khoản khách hàng ở tab „Quyền truy cập API“ và được gắn trực tiếp với API-Key tương ứng.