Tích hợp cùng SRV Holding

Xác thực

Mọi request gửi header X-API-Key. Khóa chỉ hiển thị một lần khi SRV cấp hoặc xoay khóa; không đặt khóa trong URL hay mã nguồn phía trình duyệt.

X-API-Key: srv_live_••••••••••••••••
Content-Type: application/json

Base URL: https://api.srvholding.com/api/partner/v1

1. Danh mục sản phẩm

Chỉ trả sản phẩm đang hoạt động thuộc các thương hiệu đã cấp cho API key. productCode là mã ổn định dùng khi tạo đơn. Chỉ sản phẩm có commerceMode=direct_sale được phép xuất hiện trong đơn; sản phẩm consultation chỉ nhận đăng ký tư vấn.

curl "https://api.srvholding.com/api/partner/v1/products?page=1&limit=30" \
  -H "X-API-Key: $SRV_API_KEY"

curl "https://api.srvholding.com/api/partner/v1/products/SKU-001" \
  -H "X-API-Key: $SRV_API_KEY"

2. Tạo đơn hàng

Idempotency-Key là bắt buộc và phải giữ nguyên khi retry cùng một request. Dùng lại khóa với payload khác sẽ nhận HTTP 409. Giá bán được lấy từ máy chủ, không nhận từ payload.

curl -X POST "https://api.srvholding.com/api/partner/v1/orders" \
  -H "X-API-Key: $SRV_API_KEY" \
  -H "Idempotency-Key: order-2026-000001" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "PARTNER-000001",
    "customer": {
      "name": "Nguyễn Văn A",
      "phone": "0901234567",
      "email": "a@example.com"
    },
    "shippingAddress": {
      "detail": "12 Nguyễn Huệ",
      "ward": "Bến Nghé",
      "district": "Quận 1",
      "province": "TP. Hồ Chí Minh"
    },
    "items": [
      { "productCode": "SKU-001", "quantity": 2 }
    ],
    "note": "Giao giờ hành chính"
  }'

Một đơn chỉ chứa sản phẩm của cùng một thương hiệu. Tra cứu bằng mã của đối tác:

curl "https://api.srvholding.com/api/partner/v1/orders/PARTNER-000001" \
  -H "X-API-Key: $SRV_API_KEY"

3. Webhook trạng thái đơn

Đăng ký HTTPS endpoint cho các sự kiện order.created và order.status_changed. Secret sinh tự động chỉ trả về một lần nếu request không cung cấp secret.

curl -X POST "https://api.srvholding.com/api/partner/v1/webhooks" \
  -H "X-API-Key: $SRV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production orders",
    "url": "https://partner.example.com/webhooks/srv",
    "events": ["order.created", "order.status_changed"]
  }'

SRV gửi các header X-SRV-Event, X-SRV-Event-ID, X-SRV-Timestamp và X-SRV-Signature. Chữ ký là:

sha256=HMAC_SHA256(secret, timestamp + "." + rawRequestBody)

Hãy xác minh chữ ký trên raw body, từ chối timestamp quá cũ và lưu X-SRV-Event-ID để xử lý idempotent. Endpoint cần trả HTTP 2xx; hệ thống retry tối đa theo cấu hình với backoff.

Mã phản hồi

400 payload/header không hợp lệ · 401 API key sai hoặc hết hạn · 403 thiếu scope · 404 tài nguyên ngoài phạm vi đối tác · 409 trùng mã đơn hoặc xung đột idempotency.