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.
| 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 |
- 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 theoLicenseTtlSeconds, mặc định 300s). - Refresh Token Mutex (chống xung đột xoay vòng): AppMarket xoay vòng
RefreshTokenmỗi lần gọiPOST /api/sso/refreshvà 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 (SemaphoreSlimtrong .NET hoặcSessionManagertrong@appmarket/sdk) để nhiều request song song chỉ gọi refresh đúng 1 lần. - Không bao giờ tin
?checkout=success: TạiGET /billing/return, luôn ép gọi/api/sso/refreshphí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ưulicense.versioncục bộ; nếu webhook đến trễ cóversion <= currentVersionthì 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ếuemailVerified === 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);
}
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 |
expired | Hết hạn (gói hết kỳ chế độ (a), hoặc hết quyền sử dụng) |
revoked | Đã bị thu hồi |
suspended | Tạ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_flagged | Thiết bị bị đánh dấu bất thường khi đối chiếu |
not_found | Không có license này trong các sản phẩm của bạn |
Lỗi (thân {"error":{"code","message"}}):
| HTTP | code | Khi nào |
|---|---|---|
| 400 | invalid_request | Thiếu/sai license_key, device_hash sai dạng |
| 401 | missing_api_key · invalid_api_key · key_revoked · key_expired | Thiế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) |
| 403 | insufficient_scope · key_suspended · developer_inactive | Khó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 |
| 429 | rate_limited | Vượ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_hashkhông bắt buộc ở/verify(bắt buộc ở/activatevà/deactivate). Khóa production ghi nhận slot thiết bị; khóa sandbox chỉ đọc trừ entitlement giả lậpIsSandbox = 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.
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
- 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). - 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). - Chữ ký = HMAC-SHA256(khóa, nội dung ký), viết hex chữ thường; header là
v1=<hex>. - 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. - So sánh bằng hàm thời gian không đổi (không dùng
==). - Từ chối nếu
X-Marketplace-Timestamplệ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). - 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ộ khidata.license.versionlớ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 "", 200using 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-Idkhô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-50trênWeb.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.
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.