Tài liệu B2B

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.

info Bạn không cần đơn đăng ký B2B riêng: Hãy đăng nhập bằng tài khoản khách hàng của bạn, mở tab API và tạo API-Key của bạn tại đó. Đến quyền truy cập API →

Định dạng Header

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

Ví dụ với 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

Tất cả các Endpoint đều tương đối so với Base URL sau:

Base URL
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

PlanYêu cầu / PhútYêu cầu / Ngày
Tài khoản khách hàng605.000
Giới hạn mở rộngtheo yêu cầutheo 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 OKYêu cầu thành công
400 Bad RequestTham số không hợp lệ
401 UnauthorizedThiếu hoặc không hợp lệ API-Key
403 ForbiddenKhông có quyền với tài nguyên này
404 Not FoundKhông tìm thấy tài nguyên
429 Too Many RequestsĐã vượt quá Rate Limit
500 Internal Server ErrorLỗi máy chủ – vui lòng liên hệ hỗ trợ

Định dạng Fehler-Response

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

Endpoint: Đơn hàng

GET /api/v1/orders Tất cả đơn hàng của tài khoản
ParameterLoạiMô tả
pageintegerTrang (mặc định: 1)
per_pageintegerMục trên mỗi trang (tối đa 100)
statusstringpaid | 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} Truy xuất một đơn hàng riêng lẻ

Endpoint: Thông tin sản phẩm và đơn hàng

GET /api/v1/orders/{order_id}/codes Tất cả thông tin sản phẩm của một đơn hàng
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} Truy xuất một thông tin sản phẩm riêng lẻ
warning Thông tin sản phẩm và đơn hàng chỉ được sử dụng trong phạm vi của đơn hàng và thông tin người bán tương ứng. Việc chuyển giao lạm dụng có thể vi phạm các điều khoản sử dụng.

Endpoint: Sản phẩm

GET /api/v1/products Truy xuất danh mục sản phẩm
ParameterLoạiMô tả
categorystringLọc theo Kategorie-Slug
in_stockbooleanChỉ các sản phẩm có sẵn
pageintegerTrang
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 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

EventMô tả
order.paidĐơn hàng đã được thanh toán
codes.deliveredCác mã đã được cung cấp
order.refundedĐơn hàng đã được hoàn tiền

Webhook Payload

POST – Webhook-Endpoint của bạn
{
  "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

Ai có thể sử dụng B2B API?

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.

Các phản hồi có định dạng nào?

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.

Tôi có thể đặt đơn hàng qua API không?

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ó môi trường Sandbox không?

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.