Kết nối website với BMWEB

Website của khách hàng có thể viết bằng PHP, WordPress, Node.js, C#, Python hay công nghệ nào khác. Để app BMWEB hiện được sản phẩm, đơn hàng của website đó, lập trình viên chỉ cần làm một lớp nhỏ trên website gọi là connector: vài đường dẫn HTTPS trả về JSON theo một chuẩn chung. Tài liệu này mô tả chuẩn đó.

1. Bức tranh tổng thể

• App không nói chuyện trực tiếp với website. Chỉ máy chủ BMWEB gọi connector.
• Website không bao giờ phải gọi ngược lại BMWEB.
• Sản phẩm, giá, đơn hàng và tài khoản vẫn nằm ở website. BMWEB không giữ bản sao đơn hàng hay sản phẩm của website, chỉ nhớ danh sách khả năng (capabilities) trong vài phút.
• Tài khoản đăng nhập app là chính tài khoản của website: người mua dùng tài khoản thành viên, chủ cửa hàng dùng tài khoản quản trị. Connector tự kiểm mật khẩu bằng cách của website; BMWEB không bao giờ lưu mật khẩu đó.

2. Chọn cách kết nối

3. Yêu cầu tối thiểu

• HTTPS với chứng chỉ hợp lệ (đủ chuỗi chứng chỉ trung gian). Địa chỉ phải là website công khai trên internet: BMWEB từ chối địa chỉ IP nội bộ, localhost, tên .local/.internal và một số cổng dịch vụ (SSH, cơ sở dữ liệu, thư...). Dùng cổng 443 mặc định là đủ.
• Không chuyển hướng. BMWEB không đi theo chuyển hướng (301/302), nên địa chỉ nhập vào phải là địa chỉ cuối cùng (đúng https, đúng www hoặc không, đúng dấu /).
• Trả JSON UTF-8 với Content-Type: application/json, không BOM, không in thêm cảnh báo hay HTML.
• Trả lời trong 10 giây và không quá 5 MB mỗi lần. Luôn giới hạn limit (tối đa 100).
• Đồng hồ máy chủ website đúng giờ (lệch dưới 5 phút), vì chữ ký có thời hạn.
• Một khóa bí mật dài, ngẫu nhiên (từ 32 ký tự). Bảng điều khiển BMWEB có nút "Tạo khóa" tạo sẵn khóa 48 ký tự.
• Địa chỉ nhập vào bảng điều khiển là thư mục gốc của connector, ví dụ https://www.tenmien.com/marzi-connector; BMWEB nối thêm /v1/... phía sau.

4. Khóa bí mật và chữ ký

Mọi yêu cầu BMWEB gửi đi đều có hai header. Connector phải kiểm cả hai trước khi làm bất cứ việc gì, kể cả đọc dữ liệu.

Nội dung ký gồm bốn dòng nối bằng ký tự xuống dòng \n (không có dòng trống ở cuối):

{timestamp}
{METHOD}                       (GET hoặc POST, chữ hoa)
{đường dẫn + query}            (ví dụ /v1/products?page=1&limit=20)
{sha256 hex của body}          (GET không có body: dùng sha256 của chuỗi rỗng)

Bốn quy tắc dễ sai

1. Đường dẫn ký là đường dẫn không có thư mục chứa connector. Nếu connector nằm ở https://site.com/marzi-connector thì website nhận /marzi-connector/v1/products nhưng BMWEB ký /v1/products. Hãy cắt tiền tố thư mục trước khi kiểm chữ ký và trước khi chọn route (bản mẫu có biến BASE_PATH, bản PHP có cấu hình base_path).
2. Ký đúng nguyên văn query như nhận được (thứ tự tham số, mã hóa %), đừng sắp xếp lại.
3. Hash body bằng byte gốc nhận được, đừng đọc JSON rồi dựng lại chuỗi.
4. So sánh bằng hàm so sánh thời gian cố định (hash_equals, timingSafeEqual, hmac.compare_digest...), không dùng ==. Từ chối nếu |giờ hiện tại - timestamp| > 300 giây để chặn phát lại.

secret     = test-secret-key-0123456789abcdef
timestamp  = 1700000000
method     = POST
uri        = /v1/auth/verify?x=1
body       = {"username":"khach","password":"mat khau"}

signature  = 6555990f154cc9a91c0fb5182bfb991bebcca1fed0a1f137a11f0be74d5913d7

(GET /v1/products?page=1&limit=20, body rỗng, cùng khóa và giờ)
signature  = b0c9e960e037ae0e9266c7e7c1c20e45fa8e451ae84d83b586d8df671534adb7

Mã mẫu

Ba đoạn dưới đây đã được chạy thử và cho đúng giá trị mẫu. Đoạn C# viết theo cùng công thức nhưng chưa được biên dịch và chạy thử, hãy so với giá trị mẫu trước khi dùng.

Node.js

// Node.js 18+. Check or make a MARZI signature.
const crypto = require('crypto');

/** hex( HMAC-SHA256( secret, timestamp \n METHOD \n path?query \n sha256hex(body) ) ); body is the raw text ("" for GET). */
function sign(secret, timestamp, method, uri, body) {
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  return crypto.createHmac('sha256', secret).update(`${timestamp}\n${method}\n${uri}\n${bodyHash}`).digest('hex');
}

/** True when the request really comes from MARZI. `uri` is the path + query WITHOUT the folder your connector lives in. */
function isFromMarzi(secret, headers, method, uri, body, maxSkewSeconds = 300) {
  const timestamp = String(headers['x-connector-timestamp'] || headers['x-marzi-timestamp'] || '');
  const given = String(headers['x-connector-signature'] || headers['x-marzi-signature'] || '').toLowerCase();
  if (!/^\d+$/.test(timestamp) || !given) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > maxSkewSeconds) return false; // too old: someone may be replaying it
  const expected = Buffer.from(sign(secret, timestamp, method, uri, body));
  const actual = Buffer.from(given);
  return expected.length === actual.length && crypto.timingSafeEqual(expected, actual); // never compare with ===
}

module.exports = { sign, isFromMarzi };

if (require.main === module) {
  // Test vector from the documentation: must print 6555990f154cc9a91c0fb5182bfb991bebcca1fed0a1f137a11f0be74d5913d7
  console.log(sign('test-secret-key-0123456789abcdef', '1700000000', 'POST', '/v1/auth/verify?x=1', '{"username":"khach","password":"mat khau"}'));
}

Python

"""Python 3. Check or make a MARZI signature (standard library only)."""
import hashlib
import hmac
import time


def sign(secret: str, timestamp: str, method: str, uri: str, body: bytes) -> str:
    """hex( HMAC-SHA256( secret, timestamp \\n METHOD \\n path?query \\n sha256hex(body) ) ); body is the raw bytes (b"" for GET)."""
    body_hash = hashlib.sha256(body).hexdigest()
    payload = f"{timestamp}\n{method}\n{uri}\n{body_hash}".encode()
    return hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()


def is_from_marzi(secret: str, headers: dict, method: str, uri: str, body: bytes, max_skew_seconds: int = 300) -> bool:
    """True when the request really comes from MARZI. `uri` is the path + query WITHOUT the folder your connector lives in."""
    timestamp = str(headers.get("X-Connector-Timestamp") or headers.get("X-Marzi-Timestamp", ""))
    given = str(headers.get("X-Connector-Signature") or headers.get("X-Marzi-Signature", "")).lower()
    if not timestamp.isdigit() or not given:
        return False
    if abs(time.time() - int(timestamp)) > max_skew_seconds:
        return False  # too old: someone may be replaying it
    return hmac.compare_digest(sign(secret, timestamp, method, uri, body), given)  # never compare with ==


if __name__ == "__main__":
    # Test vector from the documentation: must print 6555990f154cc9a91c0fb5182bfb991bebcca1fed0a1f137a11f0be74d5913d7
    print(sign("test-secret-key-0123456789abcdef", "1700000000", "POST", "/v1/auth/verify?x=1", '{"username":"khach","password":"mat khau"}'.encode()))

PHP

<?php
// PHP 7.4+. Check or make a MARZI signature.

/** hex( HMAC-SHA256( secret, timestamp \n METHOD \n path?query \n sha256hex(body) ) ); $body is the raw text ('' for GET). */
function marzi_sign(string $secret, string $timestamp, string $method, string $uri, string $body): string
{
    return hash_hmac('sha256', $timestamp . "\n" . $method . "\n" . $uri . "\n" . hash('sha256', $body), $secret);
}

/** True when the request really comes from MARZI. $uri is the path + query WITHOUT the folder your connector lives in. */
function marzi_is_genuine(string $secret, string $uri, int $maxSkewSeconds = 300): bool
{
    $timestamp = $_SERVER['HTTP_X_MARZI_TIMESTAMP'] ?? '';
    $given = strtolower($_SERVER['HTTP_X_MARZI_SIGNATURE'] ?? '');
    if (!ctype_digit($timestamp) || $given === '') {
        return false;
    }
    if (abs(time() - (int)$timestamp) > $maxSkewSeconds) {
        return false; // too old: someone may be replaying it
    }
    $body = file_get_contents('php://input') ?: '';
    return hash_equals(marzi_sign($secret, $timestamp, $_SERVER['REQUEST_METHOD'], $uri, $body), $given); // never compare with ==
}

if (PHP_SAPI === 'cli' && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__) {
    // Test vector from the documentation: must print 6555990f154cc9a91c0fb5182bfb991bebcca1fed0a1f137a11f0be74d5913d7
    echo marzi_sign('test-secret-key-0123456789abcdef', '1700000000', 'POST', '/v1/auth/verify?x=1', '{"username":"khach","password":"mat khau"}'), "\n";
}

C# (.NET 6+)

// C# (.NET 6+). Check or make a MARZI signature.
// NOTE: this file was written to match the other languages and the test vector, but it has NOT been compiled or run by
// the MARZI team. Check it against the test vector in the documentation before you rely on it.
using System;
using System.Security.Cryptography;
using System.Text;

public static class MarziSignature
{
    /// hex( HMAC-SHA256( secret, timestamp \n METHOD \n path?query \n sha256hex(body) ) ); body is the raw bytes (empty for GET).
    public static string Sign(string secret, string timestamp, string method, string uri, byte[] body)
    {
        var bodyHash = Convert.ToHexString(SHA256.HashData(body)).ToLowerInvariant();
        var payload = $"{timestamp}\n{method}\n{uri}\n{bodyHash}";
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        return Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload))).ToLowerInvariant();
    }

    /// True when the request really comes from MARZI. `uri` is the path + query WITHOUT the folder your connector lives in.
    public static bool IsFromMarzi(string secret, string? timestamp, string? signature, string method, string uri, byte[] body, int maxSkewSeconds = 300)
    {
        if (string.IsNullOrEmpty(timestamp) || string.IsNullOrEmpty(signature) || !long.TryParse(timestamp, out var seconds)) return false;
        if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - seconds) > maxSkewSeconds) return false; // too old: maybe a replay
        var expected = Encoding.ASCII.GetBytes(Sign(secret, timestamp, method, uri, body));
        var actual = Encoding.ASCII.GetBytes(signature.ToLowerInvariant());
        return CryptographicOperations.FixedTimeEquals(expected, actual); // never compare with ==
    }

    // Test vector from the documentation: Sign("test-secret-key-0123456789abcdef", "1700000000", "POST", "/v1/auth/verify?x=1",
    //   Encoding.UTF8.GetBytes("{\"username\":\"khach\",\"password\":\"mat khau\"}"))
    // must return 6555990f154cc9a91c0fb5182bfb991bebcca1fed0a1f137a11f0be74d5913d7
}

WordPress

Viết connector thành một plugin nhỏ: đăng ký route bằng register_rest_route('marzi/v1', ...) hoặc dùng một file PHP riêng ngoài WordPress. Lưu ý hai điều: (1) kiểm chữ ký trên đường dẫn đã bỏ tiền tố (/wp-json/marzi) và trên body thô ($request->get_body()); (2) tắt cache trang cho các đường dẫn này và cho phép chúng đi qua plugin bảo mật/tường lửa (Wordfence, Cloudflare...).

5. Làm theo từng giai đoạn

Connector khai báo ở GET /v1/capabilities những khả năng nó có. BMWEB chỉ bật tính năng tương ứng, nên bạn có thể giao từng phần. Khuyến nghị làm theo thứ tự:

6. Chi tiết từng đường dẫn

Quy ước chung: id luôn là chuỗi ("12", không phải số 12); tiền là số (không phải chuỗi) theo đơn vị nhỏ nhất của loại tiền cửa hàng đang dùng (VND, KRW không có số lẻ); thời gian theo ISO 8601 UTC; chữ nhiều ngôn ngữ ở dạng {"vi":..,"en":..,"kr":..} (tiếng Hàn là kr, không phải ko; chưa dịch thì lặp lại tiếng Việt); trường không có giá trị trả null, không bỏ trường. Phân trang bằng page (từ 1) và limit (tối đa 100). Các ví dụ dưới đây là câu trả lời thật của bản mẫu, đã rút gọn danh sách còn một phần tử.

6.1 Khả năng bắt buộc

GET /v1/capabilities

{
  "connector": "marzi-sample",
  "contract": 1,
  "capabilities": [
    "products.read",
    "categories.read",
    "auth.verify",
    "orders.read",
    "orders.create",
    "staff.verify",
    "staff.orders",
    "staff.orders.write",
    "staff.customers",
    "staff.products",
    "staff.products.write",
    "pages.read"
  ]
}

6.2 Sản phẩm: products.read, categories.read

GET /v1/products?page=1&limit=20&q=&category=&member=

{
  "items": [
    {
      "id": "1",
      "code": "BAN001",
      "names": {
        "vi": "Bánh su kem",
        "en": "Cream puffs",
        "kr": "슈크림"
      },
      "description": "Vỏ giòn, nhân kem vani béo nhẹ.",
      "price": 199000,
      "regularPrice": 35000,
      "variants": [
        {
          "id": "1-6",
          "name": "Hộp 6 cái",
          "price": 199000,
          "stock": 40
        },
        {
          "id": "1-12",
          "name": "Hộp 12 cái",
          "price": 359000,
          "stock": 25
        }
      ],
      "image": "p1.png",
      "stock": 60
    }
  ],
  "total": 9
}

• price: giá bán cho người đang xem. Sản phẩm bán theo quy cách (variants): giá thấp nhất trong các quy cách. 0 nghĩa là "liên hệ cửa hàng".
• regularPrice: giá gốc, dùng để gạch giá khi đang giảm.
• image: chỉ tên file, BMWEB ghép với thư mục ảnh bạn nhập ở bảng điều khiển (ví dụ https://site.com/upload/product/).
• variants: danh sách quy cách (hộp 6, hộp 12, size S/M/L...). Không có thì trả []. stock của quy cách là null nếu không theo dõi tồn kho.
• Chỉ trả sản phẩm đang bán (không trả sản phẩm đã ẩn).
• url (không bắt buộc): trang của sản phẩm này trên website, là đường dẫn dưới địa chỉ website (ví dụ /san-pham/ban001) hoặc địa chỉ https đầy đủ trên chính website đó. Dùng cho link chia sẻ: nếu cửa hàng chọn "chuyển thẳng sang website" ở bảng điều khiển, người chưa cài app bấm vào link sẽ được đưa tới trang này; nếu không có url, họ thấy trang giới thiệu sản phẩm của BMWEB. Địa chỉ ở website khác, hoặc không phải https, bị bỏ qua.

Một sản phẩm có quy cách:

{
  "id": "1",
  "code": "BAN001",
  "names": {
    "vi": "Bánh su kem",
    "en": "Cream puffs",
    "kr": "슈크림"
  },
  "description": "Vỏ giòn, nhân kem vani béo nhẹ.",
  "price": 199000,
  "regularPrice": 35000,
  "variants": [
    {
      "id": "1-6",
      "name": "Hộp 6 cái",
      "price": 199000,
      "stock": 40
    },
    {
      "id": "1-12",
      "name": "Hộp 12 cái",
      "price": 359000,
      "stock": 25
    }
  ],
  "image": "p1.png",
  "stock": 60
}

GET /v1/products/{id}?member= trả một sản phẩm như trên; không có hoặc đã ẩn thì trả 404.

Sản phẩm có nhiều lựa chọn (không bắt buộc)

Có hai cách, website tự chọn cách hợp với dữ liệu của mình, không cần cài đặt gì ở bảng điều khiển; app nhận ra qua dữ liệu được trả về, và hai cách dùng lẫn trong một cửa hàng được.

• Quy cách trong một sản phẩm (variants, ở trên): hợp khi các lựa chọn chỉ khác giá, ví dụ hộp 6 / hộp 12, 250g / 500g.
• Mỗi lựa chọn là một sản phẩm riêng, gom bằng group: hợp khi mỗi lựa chọn có ảnh, tồn kho, giá khuyến mãi riêng hoặc có nhiều chiều (hương vị × size, màu × cỡ). Mỗi sản phẩm vẫn là một sản phẩm đầy đủ như trên, thêm một trường group:

{
  "id": "14",
  "code": "DRK104",
  "names": {
    "vi": "Trà trái cây",
    "en": "Fruit tea",
    "kr": "과일 티"
  },
  "description": "Trà thanh mát, chọn hương vị và size theo ý bạn.",
  "price": 39000,
  "regularPrice": 46000,
  "variants": [],
  "image": "tra-dau.png",
  "stock": 18,
  "group": {
    "id": "tra-trai-cay",
    "options": [
      {
        "name": "Hương vị",
        "value": "Dâu",
        "names": { "vi": "Hương vị", "en": "Flavor", "kr": "맛" },
        "values": { "vi": "Dâu", "en": "Strawberry", "kr": "딸기" }
      },
      { "name": "Size", "value": "M" }
    ]
  }
}

• group.id: mã nhóm, giống nhau ở mọi sản phẩm của nhóm.
• group.options: lựa chọn của sản phẩm này; tên (name) và thứ tự giống nhau ở mọi sản phẩm của nhóm. names / values (vi, en, kr) là bản dịch, không bắt buộc.
• Tổ hợp không bán thì không tạo sản phẩm; app tự làm mờ. Hết hàng thì cứ để stock: 0.
• Hai tham số thêm cho GET /v1/products: collapse=1 = mỗi nhóm chỉ trả một sản phẩm (lựa chọn đầu tiên) kèm group.count (số lựa chọn) và group.priceFrom (giá thấp nhất), để danh sách không lặp; group=<mã> = trả mọi sản phẩm của nhóm đó (tối đa 50), không gom. Website không dùng nhóm thì bỏ qua cả hai.
• Nếu website chưa gom khi nhận collapse=1, BMWEB vẫn chỉ giữ một sản phẩm cho mỗi nhóm trong từng trang kết quả, nhưng tổng số và phân trang có thể lệch: nên làm đúng.

Bộ kiểm tra check.js tự kiểm thêm hai điểm trên khi website có trả group.

GET /v1/categories

{
  "items": [
    {
      "id": "banh",
      "names": {
        "vi": "Bánh ngọt",
        "en": "Pastries",
        "kr": "베이커리"
      }
    },
    {
      "id": "do-uong",
      "names": {
        "vi": "Đồ uống",
        "en": "Drinks",
        "kr": "음료"
      }
    },
    {
      "id": "qua-tang",
      "names": {
        "vi": "Quà tặng",
        "en": "Gifts",
        "kr": "선물"
      }
    }
  ]
}

6.3 Người mua: auth.verify, orders.read, orders.create

POST /v1/auth/verify, body {"username":"...","password":"..."}. Đúng thì trả thông tin người mua; sai trả 401 với "error":"invalid_credentials".

{
  "memberId": "1",
  "username": "khachmau",
  "name": "Nguyễn Thị Lan",
  "email": "lan@example.com",
  "phone": "0900000001"
}

GET /v1/members/{memberId}/orders?page=1&limit=20: đơn của người đó, mới nhất trước. GET /v1/members/{memberId}/orders/{id}: một đơn; đơn của người khác phải trả 404.

{
  "id": "1001",
  "code": "MAU1001",
  "status": "pending",
  "paid": false,
  "createdAt": "2026-10-17T03:08:45.000Z",
  "fullName": "Nguyễn Thị Lan",
  "phone": "0900000001",
  "address": "Số 12, đường Hoa Mai, Quận Mẫu",
  "note": "Giao giờ hành chính",
  "subtotal": 429000,
  "shippingFee": 0,
  "total": 429000,
  "lines": [
    {
      "productId": "1",
      "name": "Bánh su kem (Hộp 12 cái)",
      "unitPrice": 359000,
      "quantity": 1
    },
    {
      "productId": "4",
      "name": "Cà phê sữa đá (Size M)",
      "unitPrice": 35000,
      "quantity": 2
    }
  ]
}

status là trạng thái rút gọn hiển thị cho người mua: pending, confirmed, packing, shipping, delivered, cancelled. Website có trạng thái riêng thì ánh xạ về giá trị gần nhất (không rõ: pending).

GET /v1/payment-methods:

{
  "items": [
    {
      "id": "1",
      "names": {
        "vi": "Thanh toán khi nhận hàng",
        "en": "Cash on delivery",
        "kr": "현금 결제"
      }
    },
    {
      "id": "2",
      "names": {
        "vi": "Chuyển khoản",
        "en": "Bank transfer",
        "kr": "계좌 이체"
      }
    }
  ]
}

POST /v1/members/{memberId}/orders: đặt hàng. App chỉ gửi "mua gì, bao nhiêu", không bao giờ gửi giá. Website tự tính giá, kiểm tồn kho, tính phí giao hàng và tổng tiền, rồi trả đơn vừa tạo (giống GET .../orders/{id}).

{
  "items": [
    {
      "productId": "1",
      "variantId": "1-6",
      "quantity": 2
    },
    {
      "productId": "4",
      "variantId": "4-m",
      "quantity": 1
    }
  ],
  "fullName": "Nguyễn Thị Lan",
  "phone": "0900000001",
  "address": "Số 12, đường Hoa Mai, Quận Mẫu",
  "note": "Giao giờ hành chính",
  "paymentMethodId": "1"
}

Nếu không nhận đơn (hết hàng, thiếu thông tin...) trả 422 kèm message bằng tiếng Việt dễ hiểu, app sẽ hiện nguyên văn cho người mua:

{
  "error": "invalid_order",
  "message": "Giỏ hàng đang trống"
}

6.4 App quản lý: staff.*

Chủ cửa hàng đăng nhập bằng tài khoản quản trị của website. Connector phải áp đúng phân quyền của website cho từng tài khoản.

POST /v1/staff/verify, body như auth/verify. Sai mật khẩu: 401. Đúng nhưng tài khoản không được xem đơn: 403. canEdit=false nghĩa là chỉ được xem, không được sửa.

{
  "staffId": "1",
  "username": "chushop",
  "name": "Chủ cửa hàng Mẫu",
  "canEdit": true
}

Mọi đường dẫn dưới /v1/staff/{staffId}/... phải kiểm lại quyền của staffId đó ở mỗi lần gọi (đừng mặc định đã kiểm lúc đăng nhập). Không đủ quyền: 403.

{
  "error": "forbidden",
  "message": "This account may not manage orders"
}

Đơn hàng

{
  "items": [
    {
      "id": "1001",
      "code": "MAU1001",
      "status": "pending",
      "paid": false,
      "createdAt": "2026-10-17T03:08:45.000Z",
      "fullName": "Nguyễn Thị Lan",
      "phone": "0900000001",
      "address": "Số 12, đường Hoa Mai, Quận Mẫu",
      "note": "Giao giờ hành chính",
      "subtotal": 429000,
      "shippingFee": 0,
      "total": 429000,
      "lines": [
        {
          "productId": "1",
          "name": "Bánh su kem (Hộp 12 cái)",
          "unitPrice": 359000,
          "quantity": 1
        },
        {
          "productId": "4",
          "name": "Cà phê sữa đá (Size M)",
          "unitPrice": 35000,
          "quantity": 2
        }
      ],
      "statusId": 1,
      "statusNames": {
        "vi": "Mới đặt",
        "en": "New",
        "kr": "신규"
      },
      "paymentMethodNames": {
        "vi": "Thanh toán khi nhận hàng",
        "en": "Cash on delivery",
        "kr": "현금 결제"
      },
      "memberId": "1",
      "email": "lan@example.com",
      "introCode": null
    }
  ],
  "total": 12,
  "amount": 3656000
}

{
  "items": [
    {
      "id": 1,
      "names": {
        "vi": "Mới đặt",
        "en": "New",
        "kr": "신규"
      }
    },
    {
      "id": 2,
      "names": {
        "vi": "Đã xác nhận",
        "en": "Confirmed",
        "kr": "확인됨"
      }
    },
    {
      "id": 3,
      "names": {
        "vi": "Đang đóng gói",
        "en": "Packing",
        "kr": "포장 중"
      }
    },
    {
      "id": 4,
      "names": {
        "vi": "Đang giao",
        "en": "Shipping",
        "kr": "배송 중"
      }
    },
    {
      "id": 5,
      "names": {
        "vi": "Đã giao",
        "en": "Delivered",
        "kr": "배송 완료"
      }
    },
    {
      "id": 6,
      "names": {
        "vi": "Đã hủy",
        "en": "Cancelled",
        "kr": "취소됨"
      }
    }
  ]
}

{
  "newSince": 11,
  "byStatus": {
    "1": 2,
    "2": 1,
    "3": 1,
    "4": 1,
    "5": 6,
    "6": 1
  },
  "now": 1792210127
}

Khách hàng

GET .../customers?page=&limit=&q=&sort= với sort là spent (chi tiêu), orders (số đơn), recent (mua gần đây) hoặc joined (mới tham gia). Số điện thoại trong danh sách phải che bớt (090****001). GET .../customers/{id} trả đầy đủ thông tin kèm 5 đơn gần nhất.

{
  "items": [
    {
      "id": "2",
      "name": "Trần Văn Minh",
      "phoneMasked": "090****002",
      "orders": 2,
      "spent": 1486000,
      "lastOrderAt": "2026-10-16T08:08:45.000Z",
      "joinedAt": "2026-08-18T04:08:45.000Z"
    }
  ],
  "total": 6
}

Sản phẩm (cho chủ cửa hàng)

GET .../products?page=&limit=&q=&visible= (visible là 1 hoặc 0; ở đây trả cả sản phẩm đang ẩn), GET .../products/{id}.

{
  "items": [
    {
      "id": "1",
      "code": "BAN001",
      "names": {
        "vi": "Bánh su kem",
        "en": "Cream puffs",
        "kr": "슈크림"
      },
      "image": "p1.png",
      "visible": true,
      "regularPrice": 35000,
      "salePrice": 0,
      "variants": [
        {
          "id": "1-6",
          "name": "Hộp 6 cái",
          "price": 199000,
          "salePrice": 0
        },
        {
          "id": "1-12",
          "name": "Hộp 12 cái",
          "price": 389000,
          "salePrice": 359000
        }
      ],
      "stock": 60
    }
  ],
  "total": 10
}

POST .../products/{id}/visibility với {"visible": false} để ẩn/hiện. POST .../products/{id} để sửa nhanh: chỉ trường nào có mặt mới đổi; kiểm tra hết trước rồi mới ghi, một trường sai thì không đổi gì (422). Giá trong khoảng 0 đến 1.000.000.000; tên 1 đến 255 ký tự. Cả hai đều yêu cầu staff.products.write.

{
  "names": {
    "vi": "Bánh su kem vani"
  },
  "regularPrice": 36000,
  "salePrice": 0,
  "variants": [
    {
      "id": "1-6",
      "price": 199000,
      "salePrice": 189000
    }
  ]
}

6.5 Trang nội dung: pages.read

Các phần của website có thể hiện thành trang trong app (Giới thiệu, Tin tức, Khuyến mãi...). kind là single (một bài duy nhất) hoặc list (danh sách bài). key chỉ gồm chữ thường và dấu gạch ngang. count = 0 nghĩa là chưa có gì để hiện, app sẽ ẩn mục đó.

{
  "items": [
    {
      "key": "about",
      "kind": "single",
      "names": {
        "vi": "Giới thiệu",
        "en": "About us",
        "kr": "회사 소개"
      },
      "count": 1
    },
    {
      "key": "news",
      "kind": "list",
      "names": {
        "vi": "Tin tức",
        "en": "News",
        "kr": "뉴스"
      },
      "count": 2
    },
    {
      "key": "promotion",
      "kind": "list",
      "names": {
        "vi": "Khuyến mãi",
        "en": "Promotions",
        "kr": "프로모션"
      },
      "count": 1
    }
  ]
}

{
  "id": "1",
  "names": {
    "vi": "Khai trương chi nhánh mới",
    "en": "Khai trương chi nhánh mới",
    "kr": "Khai trương chi nhánh mới"
  },
  "summaries": {
    "vi": "Chúng tôi vừa mở thêm một cửa hàng.",
    "en": "Chúng tôi vừa mở thêm một cửa hàng.",
    "kr": "Chúng tôi vừa mở thêm một cửa hàng."
  },
  "image": "upload/news/n2.png",
  "publishedAt": "2026-10-12T04:08:45.000Z",
  "contents": {
    "vi": "<p>Nội dung bài viết mẫu.</p>",
    "en": "<p>Nội dung bài viết mẫu.</p>",
    "kr": "<p>Nội dung bài viết mẫu.</p>"
  }
}

image của bài viết là đường dẫn trên website (ví dụ upload/news/x.jpg), khác với ảnh sản phẩm chỉ là tên file; BMWEB ghép với "Địa chỉ website" ở bảng điều khiển.

6.6 Đăng nhập website bằng mã QR: auth.qr

Người mua hoặc chủ cửa hàng đã đăng nhập trong app BMWEB có thể đăng nhập trang web của khách bằng cách quét một mã QR hiện trên trang đăng nhập (giống đăng nhập web của Zalo, WhatsApp hay Naver). Phần "tạo phiên đăng nhập" nằm trên website của bạn; BMWEB chỉ báo lại "người này đã đồng ý".

Mã trong QR có dạng:

{
  "note": "what the QR code says",
  "link": "marzi://login?shop=mau-demo&sid=r-MGJd0ElohtJMPzHHH29xTaUGudxGbX"
}

GET /v1/qr-login/{sid}: mô tả mã (404 nếu không có, đã hết hạn, đã dùng hoặc bị từ chối). Việc xem không được làm ai đăng nhập.

{
  "sid": "r-MGJd0ElohtJMPzHHH29xTaUGudxGbX",
  "expiresAt": "2026-10-17T05:38:14.969Z",
  "site": "Cửa hàng Mẫu",
  "requester": {
    "ip": "127.0.0.1",
    "device": "Trình duyệt trên máy tính",
    "place": null,
    "startedAt": "2026-10-17T05:36:14.969Z"
  },
  "roles": [
    "member",
    "staff"
  ]
}

POST /v1/qr-login/{sid}/approve:

{
  "role": "member",
  "userId": "1"
}

{
  "ok": true
}

Mã không còn: 404. Không muốn cho tài khoản này đăng nhập bằng cách này (ví dụ quản trị bị cấm): 422 kèm lời giải thích; BMWEB hiện lời đó cho người dùng.

Website bmweb v2 không cần tự làm: bộ cài connector-bmweb.zip có sẵn trang qr-login.php và các đường dẫn trên (xem mục "Đăng nhập website bằng mã QR" trong README.md của gói).

Trang đăng nhập mẫu của bản mẫu chạy tại http://127.0.0.1:8083/demo/login (mở trong trình duyệt, quét bằng app đã nối cửa hàng mau-demo). Mã nguồn nằm trong server.js (phần "QR sign-in") và demo/login.html.

6.7 Đơn từ sàn BMWEB (không cần làm thêm gì)

Sàn BMWEB Market lấy sản phẩm của cửa hàng qua đúng những đường dẫn đã có (products.read, categories.read) và, với cửa hàng đã ký thỏa thuận phí sàn, gửi đơn qua POST /v1/members/{memberId}/orders (khả năng orders.create) như một đơn của một thành viên. Không có đường dẫn hay trường mới.

• Thành viên nhận đơn sàn: cửa hàng tạo trên website một thành viên riêng; chủ hệ thống BMWEB nhập mã thành viên đó (memberId) vào thỏa thuận. BMWEB đặt đơn dưới thành viên ấy. Họ tên, số điện thoại và địa chỉ giao hàng trong đơn là của người mua thật, không phải của thành viên.
• Ghi chú của đơn bắt đầu bằng [Sàn MARZI MK-12345678]. Đơn người mua đã chuyển khoản vào tài khoản của BMWEB có thêm chữ - ĐÃ THANH TOÁN qua MARZI, KHÔNG thu tiền khi giao trong ngoặc: website nên hiển thị ghi chú này cho nhân viên và không thu tiền lần nữa khi giao.
• Phương thức thanh toán: BMWEB chọn trong GET /v1/payment-methods phương thức có tên chứa "tiền mặt", "khi nhận hàng", "COD" hoặc "cash"; không có thì lấy phương thức đầu tiên. Nên có sẵn một phương thức như vậy.
• Website tự tính giá, phí giao, giảm giá như mọi đơn; BMWEB lấy con số website trả về làm tiền hàng khi tính phí sàn. Đơn bị từ chối (hết hàng, lỗi 422...) thì BMWEB giữ đơn lại và ghi lý do, cửa hàng không bị mất khách.
• Trạng thái: người mua trên sàn xem trạng thái đơn qua GET /v1/members/{memberId}/orders/{id} (khả năng orders.read) với cùng thành viên; hãy cập nhật trạng thái đơn trên website như bình thường.
• Cờ "đã thanh toán": khi người mua thanh toán bằng mã QR (hoặc chuyển khoản trong app cửa hàng), BMWEB chưa ghi cờ đã thanh toán về website. Khả năng này sẽ được thêm sau dưới dạng tùy chọn, không làm hỏng connector đã cài.

6.8 Khóa học và lớp học: courses.*

Cho website bán khóa học. App người mua có tab Khóa học; chủ trung tâm duyệt đăng ký trong app quản lý (hướng dẫn dùng ở Khóa học và lớp học). Website chỉ cần trả khóa, bài và ai được học gì; những thứ website hiếm khi có (học đến đâu, thời gian học, bình luận, giới hạn thiết bị) do BMWEB tự giữ, bạn không phải làm.

Một khóa trong danh sách:

{
  "items": [
    {
      "id": "1",
      "names": {
        "vi": "Lập trình PLC cơ bản",
        "en": "PLC programming basics",
        "kr": "PLC 프로그래밍 기초"
      },
      "description": "Từ con số 0 đến tự viết được chương trình điều khiển băng tải, đèn giao thông bằng PLC. Có bài tập sau mỗi chương.",
      "price": 590000,
      "regularPrice": 790000,
      "image": "khoa-plc.png",
      "lessons": 5,
      "access": "active"
    }
  ],
  "total": 3
}

Một khóa với chương và bài (rút gọn):

{
  "id": "1",
  "names": {
    "vi": "Lập trình PLC cơ bản",
    "en": "PLC programming basics",
    "kr": "PLC 프로그래밍 기초"
  },
  "description": "Từ con số 0 đến tự viết được chương trình điều khiển băng tải, đèn giao thông bằng PLC. Có bài tập sau mỗi chương.",
  "price": 590000,
  "regularPrice": 790000,
  "image": "khoa-plc.png",
  "lessons": 5,
  "access": "active",
  "sections": [
    {
      "id": "11",
      "names": {
        "vi": "Chương 1: Làm quen với PLC",
        "en": "Chapter 1: Meet the PLC",
        "kr": "Chương 1: Làm quen với PLC"
      },
      "lessons": [
        {
          "id": "101",
          "names": {
            "vi": "Bài 1: PLC là gì, dùng để làm gì",
            "en": "Lesson 1: What a PLC is",
            "kr": "Bài 1: PLC là gì, dùng để làm gì"
          },
          "free": true,
          "durationSeconds": 596,
          "hasVideo": true
        },
        {
          "id": "102",
          "names": {
            "vi": "Bài 2: Cấu tạo và đấu nối",
            "en": "Lesson 2: Parts and wiring",
            "kr": "Bài 2: Cấu tạo và đấu nối"
          },
          "free": false,
          "durationSeconds": 653,
          "hasVideo": true
        }
      ]
    }
  ]
}

Một bài học; video.kind là youtube, vimeo, mp4, hls hoặc embed (trang nhúng của dịch vụ video như Bunny Stream):

{
  "id": "102",
  "courseId": "1",
  "names": {
    "vi": "Bài 2: Cấu tạo và đấu nối",
    "en": "Lesson 2: Parts and wiring",
    "kr": "Bài 2: Cấu tạo và đấu nối"
  },
  "free": false,
  "content": "<h3>Cấu tạo</h3><p>Nguồn, CPU, ngõ vào, ngõ ra. Lưu ý đấu nối an toàn: luôn ngắt nguồn trước khi đấu dây.</p>",
  "video": {
    "kind": "mp4",
    "url": "https://example.com/video/ed.mp4"
  }
}

Học viên chưa được học bài (HTTP 403; app hiện nguyên message):

{
  "error": "not_enrolled",
  "message": "This course is not unlocked for this account"
}

Đăng ký của một học viên, và việc đăng ký một khóa:

{
  "items": [
    {
      "id": "1",
      "courseId": "1",
      "status": "active",
      "price": 590000,
      "createdAt": "2026-10-14T09:10:00+07:00",
      "activatedAt": "2026-10-14T10:00:00+07:00",
      "expiresAt": null
    },
    {
      "id": "2",
      "courseId": "2",
      "status": "pending",
      "price": 390000,
      "createdAt": "2026-10-20T20:30:00+07:00",
      "activatedAt": null,
      "expiresAt": null
    }
  ]
}

{
  "status": "pending",
  "price": 390000
}

Danh sách đăng ký cho nhân viên, và kết quả khi mở khóa:

{
  "items": [
    {
      "id": "101",
      "courseId": "2",
      "courseName": "Excel cho người đi làm",
      "memberId": "3",
      "memberName": "Lê Thu Trang",
      "phone": "0900000013",
      "price": 390000,
      "status": "pending",
      "createdAt": "2026-10-21T07:59:40.984Z"
    },
    {
      "id": "3",
      "courseId": "1",
      "courseName": "Lập trình PLC cơ bản",
      "memberId": "2",
      "memberName": "Trần Quốc Huy",
      "phone": "0900000012",
      "price": 590000,
      "status": "pending",
      "createdAt": "2026-10-21T08:15:00+07:00"
    }
  ],
  "total": 3
}

{
  "id": "3",
  "courseId": "1",
  "courseName": "Lập trình PLC cơ bản",
  "memberId": "2",
  "memberName": "Trần Quốc Huy",
  "phone": "0900000012",
  "price": 590000,
  "status": "active",
  "createdAt": "2026-10-21T08:15:00+07:00"
}

• Bài miễn phí: đặt free: true; ai đăng nhập cũng học thử được, kể cả chưa đăng ký.
• Video là của website: hãy trả đúng địa chỉ video mà trang của bạn đang dùng. Dịch vụ như Bunny Stream thường chỉ phát khi trang nhúng thuộc đúng tên miền: BMWEB mở video với địa chỉ website khai ở khách hàng (siteBaseUrl) nên vẫn phát được. Phần chữ của bài (content) không được chứa thẻ nhúng video (đã tách ra video).
• Kiểm quyền ở website: mọi quyết định "học viên này được học bài này không" nằm ở website (BMWEB chỉ hỏi và nhớ câu trả lời một phút). Chỉ nhân viên có quyền sửa mới được mở/khóa khóa học; website kiểm lại ở mỗi lần gọi staff.
• Giới hạn thiết bị không phải việc của website: BMWEB tự đếm điện thoại của mỗi học viên. Nếu website cũng có giới hạn riêng (ví dụ 4 phiên) thì hai giới hạn cùng áp dụng.
• Website bmweb v2 không cần tự làm: connector-bmweb.zip đọc các bảng khóa học, bài và đăng ký có sẵn của bmweb (tên loại sản phẩm khóa học và loại đăng ký đặt trong config.php: course_type, course_registration_type); đăng ký và mở khóa cần allow_write = true.
• Chạy thử: SAMPLE=school MARZI_SECRET=... node server.js chạy một trung tâm giả (3 khóa, học viên hocvien, quản lý quanly, mật khẩu Hoc@12345) bằng đúng chuẩn trên; video đặt ở địa chỉ VIDEO_BASE.

6.9 Đặt lịch: booking.*

Một động cơ đặt lịch dùng chung cho sân thể thao, spa, massage, cắt tóc, khách sạn, tour. Tài liệu thiết kế đầy đủ nằm ở docs/DAT_LICH.md; hướng dẫn dùng, có hình động, ở Đặt lịch. Website là nguồn sự thật: lịch trống, giá, giờ mở cửa, tiền cọc, chính sách hủy và việc không để hai người đặt trùng một giờ đều do website quyết định. BMWEB chỉ hỏi, hiện ra, nhận tiền cọc bằng mã QR và báo lại cho website.

Cơ sở và dịch vụ:

{
  "items": [
    {
      "id": "1",
      "names": {
        "vi": "Câu lạc bộ Padel Mẫu",
        "en": "Sample Padel Club",
        "kr": "Câu lạc bộ Padel Mẫu"
      },
      "address": "12 đường Thảo Điền, Quận Mẫu",
      "phone": "0281234001",
      "image": "dl-padel.png",
      "hours": [
        {
          "day": 0,
          "open": "06:00",
          "close": "22:00"
        },
        {
          "day": 1,
          "open": "06:00",
          "close": "22:00"
        },
        {
          "day": 2,
          "open": "06:00",
          "close": "22:00"
        },
        {
          "day": 3,
          "open": "06:00",
          "close": "22:00"
        },
        {
          "day": 4,
          "open": "06:00",
          "close": "22:00"
        },
        {
          "day": 5,
          "open": "06:00",
          "close": "22:00"
        },
        {
          "day": 6,
          "open": "06:00",
          "close": "22:00"
        }
      ]
    }
  ]
}

{
  "items": [
    {
      "id": "1",
      "venueId": "1",
      "names": {
        "vi": "Thuê sân padel",
        "en": "Padel court",
        "kr": "Thuê sân padel"
      },
      "description": "Sân tiêu chuẩn, giờ cao điểm 17:00-21:00 và cuối tuần giá cao hơn. Đặt 30% để giữ sân; hủy miễn phí trước 6 giờ.",
      "category": {
        "vi": "Thể thao",
        "en": "Sports",
        "kr": "Thể thao"
      },
      "kind": "slot",
      "image": "dl-padel.png",
      "priceUnit": "hour",
      "durations": [
        60,
        90,
        120
      ],
      "minGuests": 1,
      "maxGuests": 4,
      "pickResource": true,
      "repeat": true,
      "packages": true,
      "price": 250000,
      "depositPercent": 30
    }
  ]
}

Sân (tags để người đặt lọc theo có mái, có kính...) và những giờ còn trống của một sân:

{
  "items": [
    {
      "id": "1",
      "serviceIds": [
        "1"
      ],
      "names": {
        "vi": "Sân 1 (có mái)",
        "en": "Court 1 (covered)",
        "kr": "Sân 1 (có mái)"
      },
      "tags": [
        "covered"
      ],
      "capacity": 4,
      "image": null
    },
    {
      "id": "2",
      "serviceIds": [
        "1"
      ],
      "names": {
        "vi": "Sân 2 (có mái, kính)",
        "en": "Court 2 (covered, glass)",
        "kr": "Sân 2 (có mái, kính)"
      },
      "tags": [
        "covered",
        "glass"
      ],
      "capacity": 4,
      "image": null
    }
  ]
}

{
  "kind": "slot",
  "offers": [
    {
      "start": "2026-10-24T17:30",
      "end": "2026-10-24T19:00",
      "resourceId": "2",
      "resourceNames": {
        "vi": "Sân 2 (có mái, kính)",
        "en": "Court 2 (covered, glass)",
        "kr": "Sân 2 (có mái, kính)"
      },
      "tags": [
        "covered",
        "glass"
      ],
      "price": 525000,
      "left": null,
      "image": null
    },
    {
      "start": "2026-10-24T18:00",
      "end": "2026-10-24T19:30",
      "resourceId": "2",
      "resourceNames": {
        "vi": "Sân 2 (có mái, kính)",
        "en": "Court 2 (covered, glass)",
        "kr": "Sân 2 (có mái, kính)"
      },
      "tags": [
        "covered",
        "glass"
      ],
      "price": 525000,
      "left": null,
      "image": null
    }
  ]
}

Gửi yêu cầu đặt, và một lịch đang chờ cọc (pending_payment: website giữ chỗ đến deposit.dueBy, quá hạn thì tự hủy):

{
  "serviceId": "1",
  "resourceId": "2",
  "start": "2026-10-24T18:00",
  "end": "2026-10-24T19:30",
  "guests": 4,
  "note": "Sinh nhật nhóm bạn"
}

{
  "id": "5001",
  "code": "DL5001",
  "status": "pending_payment",
  "venueId": "1",
  "venueName": "Câu lạc bộ Padel Mẫu",
  "serviceId": "1",
  "serviceNames": {
    "vi": "Thuê sân padel",
    "en": "Padel court",
    "kr": "Thuê sân padel"
  },
  "resourceId": "2",
  "resourceNames": {
    "vi": "Sân 2 (có mái, kính)",
    "en": "Court 2 (covered, glass)",
    "kr": "Sân 2 (có mái, kính)"
  },
  "start": "2026-10-24T18:00",
  "end": "2026-10-24T19:30",
  "guests": 4,
  "price": 525000,
  "paidAmount": 0,
  "deposit": {
    "amount": 158000,
    "paid": false,
    "dueBy": "2026-10-21T16:50:00+07:00"
  },
  "policy": {
    "freeUntil": "2026-10-24T12:00:00+07:00",
    "lateFee": 100000
  },
  "canCancel": true,
  "cancelFee": null,
  "seriesId": null,
  "note": "Sinh nhật nhóm bạn",
  "createdAt": "2026-10-21T09:35:07.827Z"
}

Người thứ hai đặt đúng giờ đó (HTTP 409; app hiện nguyên message và tải lại giờ trống):

{
  "error": "slot_taken",
  "message": "Giờ này vừa có người đặt, hãy chọn giờ khác"
}

BMWEB báo đã nhận cọc, website xác nhận lịch:

{
  "id": "5001",
  "code": "DL5001",
  "status": "confirmed",
  "venueId": "1",
  "venueName": "Câu lạc bộ Padel Mẫu",
  "serviceId": "1",
  "serviceNames": {
    "vi": "Thuê sân padel",
    "en": "Padel court",
    "kr": "Thuê sân padel"
  },
  "resourceId": "2",
  "resourceNames": {
    "vi": "Sân 2 (có mái, kính)",
    "en": "Court 2 (covered, glass)",
    "kr": "Sân 2 (có mái, kính)"
  },
  "start": "2026-10-24T18:00",
  "end": "2026-10-24T19:30",
  "guests": 4,
  "price": 525000,
  "paidAmount": 158000,
  "deposit": {
    "amount": 158000,
    "paid": true,
    "dueBy": null
  },
  "policy": {
    "freeUntil": "2026-10-24T12:00:00+07:00",
    "lateFee": 100000
  },
  "canCancel": true,
  "cancelFee": null,
  "seriesId": null,
  "note": "Sinh nhật nhóm bạn",
  "createdAt": "2026-10-21T09:35:07.827Z"
}

Thẻ, mua thẻ, thẻ của khách (nhân viên xem), và trận mở:

{
  "items": [
    {
      "id": "1",
      "names": {
        "vi": "Thẻ 10 buổi sân padel",
        "en": "10 court sessions",
        "kr": "Thẻ 10 buổi sân padel"
      },
      "description": "10 lượt thuê sân 60-90 phút, dùng trong 6 tháng.",
      "type": "sessions",
      "price": 2000000,
      "sessions": 10,
      "validDays": 180,
      "discountPercent": null,
      "serviceIds": [
        "1"
      ]
    },
    {
      "id": "2",
      "names": {
        "vi": "Hội viên Bạc (giảm 15%)",
        "en": "Silver membership (15% off)",
        "kr": "Hội viên Bạc (giảm 15%)"
      },
      "description": "Giảm 15% mọi lượt thuê sân trong 3 tháng.",
      "type": "membership",
      "price": 600000,
      "sessions": null,
      "validDays": 90,
      "discountPercent": 15,
      "serviceIds": [
        "1"
      ]
    }
  ]
}

{
  "id": "MP5002",
  "status": "pending_payment",
  "price": 2000000
}

{
  "items": [
    {
      "id": "MP5002",
      "packageId": "1",
      "names": {
        "vi": "Thẻ 10 buổi sân padel",
        "en": "10 court sessions",
        "kr": "Thẻ 10 buổi sân padel"
      },
      "type": "sessions",
      "remaining": 10,
      "expiresAt": null,
      "status": "pending_payment",
      "memberName": "Nguyễn Hoàng Nam",
      "phone": "0900000021",
      "price": 2000000,
      "createdAt": "2026-10-21T09:35:07.865Z"
    }
  ],
  "total": 1
}

{
  "items": [
    {
      "id": "101",
      "kind": "game",
      "venueId": "1",
      "venueName": "Câu lạc bộ Padel Mẫu",
      "resourceNames": {
        "vi": "Sân 2 (có mái, kính)",
        "en": "Court 2 (covered, glass)",
        "kr": "Sân 2 (có mái, kính)"
      },
      "start": "2026-10-22T18:00",
      "end": "2026-10-22T19:30",
      "title": "Kèo tối thứ Tư",
      "level": {
        "from": 2,
        "to": 3.5,
        "kind": "match"
      },
      "capacity": 4,
      "players": [
        {
          "name": "Trần Mai Phương",
          "level": 3.5,
          "me": false
        },
        {
          "name": "Phạm Quang",
          "level": 3,
          "me": false
        },
        {
          "name": "Võ Thanh",
          "level": 2.5,
          "me": false
        }
      ],
      "pricePerPlayer": 120000,
      "status": "open",
      "joined": false,
      "host": false
    }
  ],
  "total": 5
}

Lịch của một ngày cho chủ cơ sở:

{
  "items": [
    {
      "id": "5001",
      "code": "DL5001",
      "status": "confirmed",
      "venueId": "1",
      "venueName": "Câu lạc bộ Padel Mẫu",
      "serviceId": "1",
      "serviceNames": {
        "vi": "Thuê sân padel",
        "en": "Padel court",
        "kr": "Thuê sân padel"
      },
      "resourceId": "2",
      "resourceNames": {
        "vi": "Sân 2 (có mái, kính)",
        "en": "Court 2 (covered, glass)",
        "kr": "Sân 2 (có mái, kính)"
      },
      "start": "2026-10-24T18:00",
      "end": "2026-10-24T19:30",
      "guests": 4,
      "price": 525000,
      "paidAmount": 158000,
      "deposit": {
        "amount": 158000,
        "paid": true,
        "dueBy": null
      },
      "policy": {
        "freeUntil": "2026-10-24T12:00:00+07:00",
        "lateFee": 100000
      },
      "canCancel": true,
      "cancelFee": null,
      "seriesId": null,
      "note": "Sinh nhật nhóm bạn",
      "createdAt": "2026-10-21T09:35:07.827Z",
      "customer": {
        "name": "Nguyễn Hoàng Nam",
        "phone": "0900000021"
      }
    }
  ],
  "total": 1
}

• Giờ là giờ địa phương của cơ sở, viết YYYY-MM-DDTHH:mm không kèm múi giờ; các mốc hết hạn (deposit.dueBy, policy.freeUntil) có múi giờ đầy đủ (ISO 8601).
• Chống đặt trùng ở tầng dữ liệu: kiểm tra và ghi trong cùng một giao dịch hoặc dùng khóa duy nhất (sân + giờ). Kiểm tra ở tầng ứng dụng rồi ghi sau sẽ để lọt hai người đặt cùng lúc.
• Tiền cọc: website quyết định có cọc không và bao nhiêu (deposit.amount). Có cọc thì lịch ở pending_payment và website giữ chỗ trong thời gian ngắn (dueBy). Cửa hàng chưa có tài khoản ngân hàng trong BMWEB thì app báo "liên hệ cửa hàng để chuyển cọc", nhân viên bấm "Đã nhận cọc" trong app quản lý.
• Chính sách hủy nằm trong policy của mỗi lịch (freeUntil, lateFee) để app nói rõ trước khi đặt và trước khi hủy; website tự tính và thu phí, BMWEB không trừ tiền.
• Đặt lặp lại (repeat: {every: "week", count}): tất cả hoặc không buổi nào; cả chuỗi dùng chung seriesId; tiền cọc chỉ tính ở buổi đầu.
• Thẻ buổi: đặt lịch kèm memberPackageId, website trừ một buổi và đặt price = 0 cho lịch đó; hủy miễn phí thì trả lại buổi. Hội viên giảm giá do website tự áp vào price của lịch trống và lịch đã đặt.
• Chạy thử: SAMPLE=booking MARZI_SECRET=... node server.js chạy một cơ sở giả (sân padel có giờ cao điểm, spa, tiệm tóc, khách sạn, tour, thẻ, trận mở) với tài khoản datlich (khách), quanly (sửa được), letan (chỉ xem), mật khẩu Dat@12345; đặt NO_DEMO_DAY=1 để không tự tạo sẵn lịch ngày mai. Bộ kiểm tự động booking-contract.spec.ts của BMWEB chạy đúng cơ sở giả này.

7. Mã lỗi

Khi lỗi, trả mã HTTP phù hợp và JSON {"error": "mã_ngắn", "message": "giải thích"}:

{
  "error": "unauthorized",
  "message": "Bad signature"
}

8. Kiểm thử

1. Chạy bản mẫu để xem đúng chuẩn trông thế nào.

   cd mau
   MARZI_SECRET=khoa-thu-nghiem-dai-it-nhat-16-ky-tu node server.js
   # mở cổng 8083, dữ liệu giả, tài khoản: khachmau / chushop (mật khẩu Mau@12345)

2. Chạy bộ kiểm tra tự động (chỉ cần Node.js 18 trở lên, không cài gì thêm). Nó gọi connector đúng như BMWEB gọi, kiểm chữ ký, kiểm hình dạng JSON từng đường dẫn, và chỉ đọc, không đặt đơn hay sửa gì.

   node check.js https://www.tenmien.com/marzi-connector KHOA_BI_MAT \
     --member tai-khoan-nguoi-mua:mat-khau --staff tai-khoan-quan-tri:mat-khau

   Kết quả mẫu (rút gọn):

   Chữ ký và an toàn
     [đạt] Từ chối yêu cầu ký sai khóa
     [đạt] Từ chối yêu cầu quá cũ (chống phát lại)
     [đạt] Từ chối yêu cầu không có chữ ký
   Sản phẩm (products.read)
     [đạt] GET /v1/products
     [LỖI] GET /v1/products/{id} - product.price: là string ("35000"), cần number
   Kết quả: 24 đạt, 1 lỗi.

3. Nhập vào bảng điều khiển BMWEB (mục "Nguồn dữ liệu" của khách hàng): địa chỉ connector, khóa bí mật, bấm Thử kết nối. Thành công sẽ liệt kê các khả năng website cung cấp.
4. Thử bằng tay trong app những việc bộ kiểm tra không tự làm vì có ghi dữ liệu: đặt một đơn thử, đổi trạng thái đơn, đánh dấu đã thanh toán, bật/tắt và sửa giá một sản phẩm thử.

Với website thật, nên tạo tài khoản thử riêng cho người mua và cho quản trị để dùng khi kiểm tra.

9. Lỗi thường gặp

10. Bảo mật cho connector

• Khóa bí mật không nằm trong thư mục web công khai và không đưa vào git. Đặt trong file cấu hình ngoài thư mục gốc web hoặc biến môi trường. Không ghi khóa, mật khẩu hay nội dung body đăng nhập vào log.
• Kiểm chữ ký trước tiên, cho mọi yêu cầu, kể cả đọc sản phẩm. Từ chối mọi thứ khác với 401.
• Giá do website quyết định. Khi nhận đơn, tự tra giá, quy cách, tồn kho từ dữ liệu của website. Không tin giá hay tổng tiền từ bên gọi.
• Tách quyền cơ sở dữ liệu. Dùng tài khoản chỉ đọc cho các đường dẫn đọc, và một tài khoản riêng quyền tối thiểu cho việc ghi đơn (như connector của VIETFOOD đang làm). Dùng câu lệnh có tham số, không ghép chuỗi SQL.
• Chỉ trả đúng phần được phép: người mua chỉ thấy đơn của chính mình (đơn người khác: 404); danh sách khách hàng che số điện thoại; sản phẩm ẩn không lộ cho người mua.
• Không để lộ chi tiết lỗi (đường dẫn file, câu SQL, stack trace). Ghi vào log nội bộ và trả 500 với thông báo chung.
• Chỉ HTTPS, giữ chứng chỉ còn hạn. Cập nhật PHP/Node/.NET/Python và thư viện đều đặn.
• Khi đổi khóa bí mật: đổi ở cả hai nơi cùng lúc (website và bảng điều khiển BMWEB, nút "Đổi địa chỉ / khóa").

11. Tải về