Tài liệu Tích hợp Nhà phát triển (API / SSO / SDK)

Hướng dẫn thống nhất 3 mô hình tích hợp AppMarket: Web/SaaS SSO, Ứng dụng cài đặt (License Key & Offline JWT) và Không cần code (PayLink). Tạo khóa và cấu hình ứng dụng trên cổng Web.Dev.

Chọn mô hình tích hợp (3-Track Decision Guide)
Hướng tích hợp Phù hợp với Thành phần AppMarket dùng Điểm bắt đầu nhanh
Track 1: Web / SaaS Ứng dụng web có backend, SaaS đa người dùng, B2B tổ chức SCR-48B SSO (PKCE S256 + JWKS), GET /api/sso/plans, GET /checkout, SCR-49 Webhook HMAC, SCR-50 Sandbox Lifecycle @appmarket/sdk (AppMarket/sdk/node/appmarket-sdk) hoặc Samples/ExternalSsoDemo (.NET 9)
Track 2: Ứng dụng cài đặt Desktop (Windows/macOS), Add-in, On-Premise chạy offline SCR-48 API Key (amk_...), POST /api/v1/license/verify, /activate, /deactivate, GET /api/v1/jwks (RS256 offline JWT) Tab REST / Offline JWT bên dưới hoặc client.activateLicense() trong @appmarket/sdk
Track 3: Không cần code Bán phần mềm nhỏ lẻ, giao key thủ công, chưa cần viết backend SCR-41 PayLink GET /buy/{linkCode} + SCR-40 Giao license thủ công (người mua xem key tại SCR-17) Tạo gói ở SCR-37 → sao chép đường dẫn /buy/{code} ở SCR-41
Kiến trúc khuyến nghị cho Web / SaaS (Track 1)
  • Single-Chokepoint getEntitlement(): Mọi route và tính năng trả phí đều đi qua duy nhất một hàm kiểm tra bản quyền đọc từ bộ nhớ/DB cục bộ (đồng bộ tức thì bằng Webhook và làm mới dự phòng theo LicenseTtlSeconds, mặc định 300s).
  • Refresh Token Mutex (chống xung đột xoay vòng): AppMarket xoay vòng RefreshToken mỗi lần gọi POST /api/sso/refresh và có cơ chế phát hiện dùng lại token (reuse detection). Luôn bọc lời gọi refresh bằng khóa theo từng phiên (SemaphoreSlim trong .NET hoặc SessionManager trong @appmarket/sdk) để nhiều request song song chỉ gọi refresh đúng 1 lần.
  • Không bao giờ tin ?checkout=success: Tại GET /billing/return, luôn ép gọi /api/sso/refresh phía backend hoặc chờ Webhook đã xác minh chữ ký mới mở khóa tính năng.
  • Thứ tự đơn điệu license.version: Lưu license.version cục bộ; nếu webhook đến trễ có version <= currentVersion thì bỏ qua (trả 200).
  • Di trú người dùng cũ (Legacy Migration): Chỉ tự liên kết tài khoản cũ theo email khi user.emailVerified === true. Nếu emailVerified === false, tuyệt đối không tự gộp tài khoản để ngăn chiếm đoạt tài khoản.
// Kiến trúc Single-Chokepoint getEntitlement(): mọi endpoint/tính năng chỉ kiểm tra qua 1 hàm duy nhất
async function getEntitlement(req) {
  // 1. Đọc bản quyền cục bộ từ session / DB (được cập nhật tức thì qua Webhook theo license.version tăng đơn điệu)
  const synced = await sessionManager.syncSession(req.session?.sid, req.session?.userId); // có per-session Mutex khi refresh!
  const lic = synced?.license;
  if (!lic || !lic.hasAccess) {
    return { allowed: false, planCode: lic?.planCode ?? 'free', features: lic?.features ?? {}, status: lic?.status ?? 'none' };
  }
  return { allowed: true, planCode: lic.planCode, tier: lic.tier, features: lic.features ?? {}, version: lic.version, status: lic.status };
}

// Di trú tài khoản cũ (Legacy Migration): CHỈ tự liên kết theo email khi emailVerified === true!
function linkAppMarketUser(localDb, amUser) {
  const bySub = localDb.findByAppMarketId(amUser.id);
  if (bySub) return bySub;
  if (amUser.emailVerified === true) {
    const byEmail = localDb.findByEmail(amUser.email);
    if (byEmail) return localDb.attachAppMarketId(byEmail.id, amUser.id);
  }
  // Email chưa xác minh: KHÔNG tự gộp tài khoản (chống Account Takeover), yêu cầu user đăng nhập mật khẩu cũ để liên kết tay.
  return localDb.createOrPromptManualLink(amUser);
}
API kiểm tra & kích hoạt license (Track 2) + SDK chính thức

1. Kiểm tra license trực tuyến (POST /api/v1/license/verify)

POST /api/v1/license/verify
Authorization: Bearer <API_KEY>
Content-Type: application/json

{ "license_key": "XXXX-XXXX", "device_hash": "sha256:<64 ký tự hex>" }

→ 200 { "status": "active", "expires_at": "2027-01-01", "support_until": "2027-01-01",
        "expiry_mode": null, "plan_code": "pro", "version": 3, "features": { "ai_export": true },
        "activations_used": 1, "activation_limit": 3, "environment": "production" }

2. Kích hoạt thiết bị, phát hành offline_token RS256 & hủy kích hoạt

POST /api/v1/license/activate
Authorization: Bearer <API_KEY>
Content-Type: application/json

{ "license_key": "AMK-LIC-XXXX", "device_hash": "sha256:<64 hex>", "device_label": "Workstation-01" }

→ 200 { "status": "active", "offline_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
        "expires_at": "2027-01-01", "support_until": "2027-01-01", "expiry_mode": "b",
        "plan_code": "lifetime", "version": 1, "activations_used": 1, "activation_limit": 3,
        "environment": "production", "update_policy": "updates_included" }

// Hủy kích hoạt trả lại slot thiết bị:
POST /api/v1/license/deactivate
{ "license_key": "AMK-LIC-XXXX", "device_hash": "sha256:<64 hex>" }

// Khóa công khai RS256 xác thực offline_token không cần Internet:
GET /api/v1/jwks

Gọi nhanh bằng curl

curl -sS https://<tên-miền-marketplace>/api/v1/license/verify \
  -H "Authorization: Bearer $MKT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"license_key":"XXXX-XXXX","device_hash":"sha256:<64 ký tự hex>"}'

Giá trị status (luôn trả HTTP 200 khi khóa API hợp lệ):

statusÝ nghĩa
activeĐang có quyền sử dụng
graceĐang trong thời gian ân hạn
expiredHết hạn (gói hết kỳ chế độ (a), hoặc hết quyền sử dụng)
revokedĐã bị thu hồi
suspendedTạm khóa do tranh chấp thẻ
device_limitĐã đủ số thiết bị kích hoạt, thiết bị này chưa được thêm
device_flaggedThiết bị bị đánh dấu bất thường khi đối chiếu
not_foundKhông có license này trong các sản phẩm của bạn

Lỗi (thân {"error":{"code","message"}}):

HTTPcodeKhi nào
400invalid_requestThiếu/sai license_key, device_hash sai dạng
401missing_api_key · invalid_api_key · key_revoked · key_expiredThiếu, sai, đã thu hồi hoặc hết hiệu lực (khóa cũ sau khi xoay vòng hết thời gian chồng lấp)
403insufficient_scope · key_suspended · developer_inactiveKhóa thiếu quyền license:verify, bị tạm khóa, hoặc tài khoản nhà phát triển không hoạt động
429rate_limitedVượt giới hạn yêu cầu mỗi phút; xem header Retry-After. Vượt liên tục sẽ bị tự động tạm khóa khóa API
  • Chỉ tra được license của sản phẩm thuộc nhà phát triển sở hữu khóa API.
  • device_hash không bắt buộc ở /verify (bắt buộc ở /activate và /deactivate). Khóa production ghi nhận slot thiết bị; khóa sandbox chỉ đọc trừ entitlement giả lập IsSandbox = true.
  • Gọi từ máy chủ của bạn. Không nhúng khóa API vào ứng dụng phát hành cho người dùng cuối.

SDK Node.js chính thức (0 thư viện ngoài, Node.js ≥ 20) nằm tại AppMarket/sdk/node/appmarket-sdk, hỗ trợ cả Track 1 (Web/SaaS) và Track 2 (Installed App + Offline RS256 JWT):

// Official Node.js SDK (@appmarket/sdk — 0 thư viện ngoài, Node >= 20)
// Đường dẫn trong repo: AppMarket/sdk/node/appmarket-sdk
const {
  loadConfig, createClient, JsonFileStore, createSessionManager,
  createWebhookMiddleware, createSessionSyncMiddleware,
  handleLogin, handleCallback, handleLogout, handleBillingReturn,
} = require('@appmarket/sdk');

const config = loadConfig({ baseUrl: 'https://app.cuaban.vn' });
const client = createClient(config);
const store = new JsonFileStore('./data/appmarket-state.json');
const sessionManager = createSessionManager({ client, store });

// 1) Mount Webhook TRƯỚC express.json() để giữ raw body cho HMAC-SHA256 dual-key
app.post('/webhooks/appmarket', createWebhookMiddleware({ config, store }));

// 2) Đồng bộ phiên tự động (có per-session mutex chống xung đột refresh token rotation)
app.use(createSessionSyncMiddleware({ sessionManager }));

// 3) Các route SSO, Plans VND & Billing Return (không bao giờ tin ?checkout=success)
app.get('/auth/appmarket/login', handleLogin({ client, flowStore: store }));
app.get('/sso/callback', handleCallback({ client, sessionManager }));
app.post('/logout', handleLogout({ client, sessionManager }));
app.get('/billing/return', handleBillingReturn({ sessionManager, redirectTo: '/billing' }));

Bộ giả lập cục bộ (0 thư viện ngoài, Node.js ≥ 20) tại AppMarket/tools/appmarket-local-emulator mô phỏng đầy đủ SSO, Plans VND/VAT, Checkout, Webhook xoay khóa kép, Installed App Offline JWT và PayLink:

# Chạy Local Emulator (0 thư viện ngoài, Node.js >= 20) — giả lập 100% giao thức thật AppMarket
cd AppMarket/tools/appmarket-local-emulator

# Khởi động máy chủ giả lập tại http://localhost:4000 (Sandbox UI: http://localhost:4000/admin)
node server.js

# Chạy bộ kiểm thử tự động E2E toàn diện (SSO, Plans, Checkout, Mutex, Webhook dual-key, Installed Offline JWT, PayLink)
node e2e.js

Sao chép đoạn hướng dẫn dưới đây cho công cụ AI của bạn:

Hãy tích hợp AppMarket theo đúng 1 trong 3 hướng: (1) Web/SaaS dùng @appmarket/sdk (AppMarket/sdk/node/appmarket-sdk) với Cross-Domain SSO PKCE S256, single-chokepoint getEntitlement(), khóa mutex per-session khi gọi /api/sso/refresh, Plans API GET /api/sso/plans, Checkout /checkout, không bao giờ tin ?checkout=success ở /billing/return (ép refresh), liên kết user cũ chỉ khi emailVerified === true; (2) Installed App gọi POST /api/v1/license/verify & /activate (Bearer amk_... từ backend hoặc xác thực offline_token RS256 qua GET /api/v1/jwks); (3) Webhook đọc raw body, xác minh X-Marketplace-Signature (hỗ trợ dual-key v1=<new>,v1=<old>) + X-Marketplace-Timestamp (<=300s), dedup event_id, chỉ áp dụng khi license.version lớn hơn phiên bản hiện tại.
Xác minh chữ ký webhook (Dual-Key Rotation & Monotonic Version)

Mỗi webhook gửi tới endpoint HTTPS của bạn đều được ký. Luôn kiểm chữ ký trước khi xử lý, nếu không bất kỳ ai biết URL đều có thể giả sự kiện. Payload tuân thủ REQ-74 (tối thiểu PII — không chứa email/SĐT, dùng affected_user_ids, owner_id, buyer_pseudonym và license.version).

POST https://<endpoint-của-bạn>
Content-Type: application/json
User-Agent: AppMarket-Webhook/1.0
X-Marketplace-Event-Id: evt_…            (giữ nguyên khi gửi lại → dùng để chống xử lý trùng)
X-Marketplace-Event-Type: payment.succeeded
X-Marketplace-Timestamp: 1763366400      (giây Unix, UTC)
X-Marketplace-Signature: v1=3f1c…        (trong lúc xoay secret: v1=<mới>,v1=<cũ>)

{"event_id":"evt_…","type":"payment.succeeded","environment":"production","sequence":1,
 "occurred_at":"2026-11-17T08:00:00Z","data":{ … }}

Cách ký & xoay khóa kép

  1. Khóa = nguyên chuỗi secret whsec_… (mã hóa UTF-8, gồm cả tiền tố whsec_). Secret hiện một lần khi tạo/xoay ở trang Webhook (SCR-49, hỗ trợ endpoint chung hoặc riêng từng sản phẩm).
  2. Nội dung ký = {X-Marketplace-Timestamp}.{thân yêu cầu THÔ} (đúng từng byte nhận được, không phân tích rồi tuần tự hóa lại).
  3. Chữ ký = HMAC-SHA256(khóa, nội dung ký), viết hex chữ thường; header là v1=<hex>.
  4. Trong thời gian chồng lấp khi xoay secret header có hai giá trị v1=<mới>,v1=<cũ>. Chấp nhận nếu khớp bất kỳ giá trị nào trong danh sách [secretMoi, secretCu], rồi gỡ secret cũ sau khi hết cửa sổ chồng lấp.
  5. So sánh bằng hàm thời gian không đổi (không dùng ==).
  6. Từ chối nếu X-Marketplace-Timestamp lệch quá 5 phút (300 giây) so với giờ máy chủ của bạn (chống phát lại).
  7. Lưu X-Marketplace-Event-Id để chống xử lý trùng (idempotency) và chỉ cập nhật bản quyền cục bộ khi data.license.version lớn hơn phiên bản đang lưu.

Mã mẫu

import crypto from 'node:crypto';
import express from 'express';

export function verifyWebhook(rawBody, signatureHeader, timestampHeader, secrets, toleranceSec = 300) {
  if (!/^\d+$/.test(timestampHeader ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestampHeader)) > toleranceSec) return false;   // chống phát lại
  const signed = Buffer.concat([Buffer.from(timestampHeader + '.'), rawBody]);
  const candidates = (signatureHeader ?? '').split(',').map(s => s.trim())
    .filter(s => s.startsWith('v1=')).map(s => s.slice(3));
  for (const secret of secrets) {
    const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');
    for (const c of candidates) {
      const a = Buffer.from(expected), b = Buffer.from(c);
      if (a.length === b.length && crypto.timingSafeEqual(a, b)) return true;
    }
  }
  return false;
}

const app = express();
// PHẢI dùng thân thô (raw), không để express.json() phân tích rồi tuần tự hóa lại.
app.post('/webhooks/marketplace', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyWebhook(req.body, req.get('X-Marketplace-Signature'), req.get('X-Marketplace-Timestamp'),
                           [process.env.MKT_WEBHOOK_SECRET]);
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString('utf8'));
  // TODO: bỏ qua nếu event.event_id đã xử lý; xử lý xong mới trả 2xx
  res.sendStatus(200);
});
import hashlib, hmac, os, time
from flask import Flask, request, abort

def verify_webhook(raw_body: bytes, signature_header: str, timestamp_header: str,
                   secrets: list[str], tolerance: int = 300) -> bool:
    if not (timestamp_header or "").isdigit():
        return False
    if abs(time.time() - int(timestamp_header)) > tolerance:      # chống phát lại
        return False
    signed = timestamp_header.encode() + b"." + raw_body
    candidates = [p.strip()[3:] for p in (signature_header or "").split(",") if p.strip().startswith("v1=")]
    for secret in secrets:
        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, c) for c in candidates):
            return True
    return False

app = Flask(__name__)

@app.post("/webhooks/marketplace")
def webhook():
    raw = request.get_data()          # thân thô, trước khi parse JSON
    if not verify_webhook(raw, request.headers.get("X-Marketplace-Signature"),
                          request.headers.get("X-Marketplace-Timestamp"),
                          [os.environ["MKT_WEBHOOK_SECRET"]]):
        abort(400)
    event = request.get_json()
    # TODO: bỏ qua nếu event["event_id"] đã xử lý
    return "", 200
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

public static class MarketplaceWebhook
{
    public static bool Verify(byte[] rawBody, string? signatureHeader, string? timestampHeader,
                              IEnumerable<string> secrets, int toleranceSeconds = 300)
    {
        if (!long.TryParse(timestampHeader, NumberStyles.None, CultureInfo.InvariantCulture, out var ts)) return false;
        if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > toleranceSeconds) return false;   // chống phát lại
        var signed = Encoding.UTF8.GetBytes(timestampHeader + ".").Concat(rawBody).ToArray();
        var candidates = (signatureHeader ?? "").Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries)
            .Where(p => p.StartsWith("v1=", StringComparison.Ordinal)).Select(p => p[3..]).ToList();
        foreach (var secret in secrets)
        {
            var expected = Convert.ToHexString(HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), signed)).ToLowerInvariant();
            foreach (var c in candidates)
                if (CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(c)))
                    return true;
        }
        return false;
    }
}

// ASP.NET Core minimal API: đọc thân thô trước khi parse JSON
// app.MapPost("/webhooks/marketplace", async (HttpRequest req) =>
// {
//     using var ms = new MemoryStream(); await req.Body.CopyToAsync(ms);
//     var ok = MarketplaceWebhook.Verify(ms.ToArray(), req.Headers["X-Marketplace-Signature"],
//                                        req.Headers["X-Marketplace-Timestamp"], new[] { secret });
//     return ok ? Results.Ok() : Results.BadRequest();
// });
<?php
function verify_webhook(string $rawBody, ?string $sigHeader, ?string $tsHeader, array $secrets, int $tolerance = 300): bool {
    if ($tsHeader === null || !ctype_digit($tsHeader)) return false;
    if (abs(time() - (int)$tsHeader) > $tolerance) return false;          // chống phát lại
    $signed = $tsHeader . '.' . $rawBody;
    $candidates = [];
    foreach (explode(',', (string)$sigHeader) as $p) {
        $p = trim($p);
        if (str_starts_with($p, 'v1=')) $candidates[] = substr($p, 3);
    }
    foreach ($secrets as $secret) {
        $expected = hash_hmac('sha256', $signed, $secret);
        foreach ($candidates as $c) if (hash_equals($expected, $c)) return true;
    }
    return false;
}

$raw = file_get_contents('php://input');   // thân thô
$ok = verify_webhook($raw, $_SERVER['HTTP_X_MARKETPLACE_SIGNATURE'] ?? null,
                     $_SERVER['HTTP_X_MARKETPLACE_TIMESTAMP'] ?? null, [getenv('MKT_WEBHOOK_SECRET')]);
if (!$ok) { http_response_code(400); exit; }
http_response_code(200);

Vận hành & Kiểm thử

  • Trả mã 2xx trong 8 giây. Hệ thống không theo chuyển hướng (3xx) và không đọc thân phản hồi.
  • X-Marketplace-Event-Id không đổi khi gửi lại: lưu id đã xử lý để chống xử lý trùng.
  • Dùng Mô phỏng vòng đời License (Sandbox) tại SCR-50 trên Web.Dev để bắn thử toàn bộ vòng đời (grant, trial, renew, fail_renewal, expire, upgrade, refund, dispute_hold, resume) ngay cả khi sản phẩm đang ở trạng thái Nháp.
Luồng liên quan trên Web.Dev: SCR-37 Gói, giá & Danh mục tính năng · SCR-48 Khóa API & secret · SCR-48B Ứng dụng SSO · SCR-49 Webhook & nhật ký gửi · SCR-50 Sandbox & tự kiểm tra tích hợp.