Kết nối shop của bạn với BEOMAM API

GET /services

Trả danh mục sản phẩm đại lý được phép mua, cùng mức giá hiệu lực theo API Key.

curl -sS 'https://beomempo.duckdns.org/api/reseller/v1/services?limit=100&offset=0' \
  -H 'Authorization: Bearer bm_live_YOUR_API_KEY'

{
  "success": true,
  "data": [{
    "id": 123,
    "sku": "BM-000123",
    "name": "Sản phẩm mẫu",
    "type": "api",
    "unit_price_vnd": 10000,
    "min_quantity": 1,
    "max_quantity": 50,
    "input_required": false,
    "input_label": null,
    "flat_price": false
  }],
  "limit": 100,
  "offset": 0
}

Các giá trị ID và giá trong ví dụ chỉ minh họa, không phải sản phẩm đang mở bán. Tham số limit từ 1 đến 100, offset từ 0 đến 100000.

GET /wallet

Kiểm tra số dư ví BEOMAM gắn với tài khoản API Key.

curl -sS 'https://beomempo.duckdns.org/api/reseller/v1/wallet' \
  -H 'Authorization: Bearer bm_live_YOUR_API_KEY'

{ "success": true, "data": { "balance_vnd": 100000, "currency": "VND" } }

GET /wallet/transactions

Lấy các bút toán ví gần nhất của đại lý (tối đa 100 bản ghi một lần).

curl -sS 'https://beomempo.duckdns.org/api/reseller/v1/wallet/transactions?limit=30' \
  -H 'Authorization: Bearer bm_live_YOUR_API_KEY'

{
  "success": true,
  "data": [{
    "type": "api_item_refund",
    "amount_vnd": 10000,
    "balance_after_vnd": 90000,
    "reference_type": "api_order_item",
    "reference_id": "456",
    "created_at": "2026-10-16T01:00:00+00:00"
  }]
}

Ví dụ chỉ minh họa cấu trúc. Giá trị thực phụ thuộc lịch sử bút toán trên tài khoản đại lý.

POST /orders

Đặt mua sản phẩm bằng mã đơn riêng client_ref. Thành công trả HTTP 201. API Key dùng số dư tài khoản đại lý hiện hữu.

curl -sS -X POST 'https://beomempo.duckdns.org/api/reseller/v1/orders' \
  -H 'Authorization: Bearer bm_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_ref": "reseller-order-100001",
    "product_id": 123,
    "quantity": 1,
    "expected_total_vnd": 10000,
    "customer_inputs": [],
    "api_options": {"accounts": ["example_user"]}
  }'

{
  "success": true,
  "replayed": false,
  "data": {
    "order_id": "BM-EXAMPLE-ORDER",
    "status": "processing",
    "payment_status": "paid",
    "quantity": 1,
    "charged_vnd": 10000,
    "refunded_vnd": 0,
    "delivery": null,
    "phone": null,
    "code": null,
    "created_at": "2026-10-16T01:00:00+00:00"
  }
}

Trạng thái và dữ liệu thực tế có thể khác theo kết quả đơn. Với hàng API, đơn được dispatch sau khi tạo; việc nhà cung cấp tiếp nhận hoặc hoàn tiền được phản ánh khi kiểm tra lại.

GET /orders/{client_ref}

Tra cứu đơn theo đúng mã client_ref đã dùng lúc đặt. Không truyền mã đơn nguồn nhà cung cấp.

curl -sS 'https://beomempo.duckdns.org/api/reseller/v1/orders/reseller-order-100001' \
  -H 'Authorization: Bearer bm_live_YOUR_API_KEY'

Trả thông tin data gồm trạng thái đơn, payment_status, charged_vnd, refunded_vnd, delivery, phone, code, created_at và dispatch_state.

Nhận kết quả tự động qua Webhook

Bot hoặc website đại lý có thể đăng ký một địa chỉ HTTPS công khai. BEOMAM gửi order.updated mỗi khi trạng thái/kết quả/số tiền hoàn trong API thay đổi. Đại lý không cần liên tục hỏi kết quả. Trường hợp webhook chưa bật hoặc bị lỗi, vẫn có thể gọi GET /orders/{client_ref}.

Không có webhook nhận đơn mua. Webhook chỉ gửi kết quả về hệ thống đại lý, không phát sinh giao dịch tài chính mới.

curl -sS -X PUT 'https://beomempo.duckdns.org/api/reseller/v1/webhook' \
  -H 'Authorization: Bearer bm_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-bot.example.com/beomam-events"}'

Webhook URL phải là domain HTTPS công khai, cổng 443. BEOMAM trả secret chỉ một lần khi đăng ký. Lưu vào máy chủ đại lý để xác minh HMAC. Cập nhật URL hoặc Secret qua PUT sẽ xoay Secret; nếu đã thiết lập webhook trước đó, phải lưu Secret mới.

{"success":true,"enabled":true,"url":"https://your-bot.example.com/beomam-events","secret":"GENERATED_ONCE"}

{
  "event": "order.updated",
  "client_ref": "reseller-order-100001",
  "at": "2026-10-16T06:00:00+00:00",
  "data": {
    "order_id": "BM-EXAMPLE-ORDER",
    "status": "completed",
    "payment_status": "paid",
    "quantity": 1,
    "charged_vnd": 10000,
    "refunded_vnd": 0,
    "delivery": "Kết quả mẫu",
    "phone": null,
    "code": null,
    "created_at": "2026-10-16T05:00:00+00:00"
  }
}

Headers: X-Event, X-Delivery-Id, X-Signature: sha256=... (HMAC SHA256 của raw request body với Secret). Trả HTTP 2xx trong 5 giây; nếu lỗi BEOMAM thử lại tối đa 10 lượt. Đại lý phải chống trùng theo X-Delivery-Id, không giả định callback luôn theo thứ tự.

import hashlib, hmac

def verify(secret, body: bytes, signature: str) -> bool:
    digest = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + digest, signature or "")

Quản lý: GET /webhook xem cấu hình (không lộ Secret), DELETE /webhook tắt, POST /webhook/test xếp hàng sự kiện ping, GET /webhook/deliveries xem kết quả gửi gần nhất. Chỉ gửi cho đơn tạo sau khi đăng ký webhook. Webhook của shop cần được bật bởi Admin sau khi kiểm thử.