Zenify Merchant OS

Zenify được coi như một merchant/service provider trong MCV Business OS. zenify.cx vẫn là site marketing, web.zenify.cx vẫn là CRM product app, nhưng khách hàng đăng ký Zenify phải trở thành user và account trong app.mcv.network.

Mục Tiêu

• Zenify là một merchant account trong Business OS, có năng lực bán sản phẩm/dịch vụ số.
• Khách hàng đăng ký trên Zenify được đồng bộ thành User và customer Account trong Business OS.
• Subscription/contract của Zenify được lưu trong Billing OS để MCV quản trị nhắc thanh toán, QR Pay, công nợ và entitlement.
• Profile chuẩn vẫn nằm ở app.mcv.network/profile; Zenify chỉ giữ dữ liệu vận hành CRM cần thiết.

Luồng Đồng Bộ Signup

sequenceDiagram
    participant Visitor as Khách đăng ký
    participant Zenify as web.zenify.cx
    participant OS as app.mcv.network
    participant Billing as Billing OS

    Visitor->>Zenify: Submit signup / trial form
    Zenify->>Zenify: Tạo SignupLead / workspace CRM
    Zenify->>OS: POST /integrations/zenify/signups<br/>HMAC signed payload
    OS->>OS: Verify signature + TTL
    OS->>OS: Upsert User + customer Account
    OS->>OS: Ensure Zenify merchant Account
    OS->>Billing: Upsert Zenify service contract
    OS-->>Zenify: user_id, account_id, contract_number
    Zenify-->>Visitor: Hoàn tất đăng ký / vào CRM

Mapping Dữ Liệu

Zenify	Business OS	Ghi chú
SignupLead.email	users.email	Khóa chính để upsert user
SignupLead.name	users.name	Nếu thiếu dùng company hoặc prefix email
SignupLead.companyName	users.company_name, accounts.name	Account khách hàng đại diện doanh nghiệp/người dùng
workspaceSlug	service_contracts.metadata.workspace_slug	Dùng để nối entitlement CRM
planCode	service_contracts.metadata.plan_code	Gói Zenify
recurringAmountVnd	service_contracts.recurring_amount	Đơn vị mặc định VND
SignupLead.id hoặc workspaceSlug	external_source_records.source_id	Chống đồng bộ trùng

Endpoint

Business OS nhận signup từ Zenify qua:

POST https://app.mcv.network/integrations/zenify/signups
X-MCV-Timestamp: 1784567890
X-MCV-Signature: sha256=<hmac_sha256(timestamp + "." + raw_json_body, shared_secret)>
Content-Type: application/json

Payload tối thiểu:

{
  "email": "customer@example.com",
  "name": "Customer Name",
  "company_name": "Customer Company",
  "workspace_slug": "customer-company",
  "plan_code": "zenify-crm",
  "plan_name": "Zenify CRM",
  "status": "trial",
  "recurring_amount_vnd": 0
}

Response thành công:

{
  "message": "Zenify signup synced.",
  "data": {
    "user_id": 1,
    "account_id": 10,
    "merchant_account_id": 11,
    "service_contract_id": 20,
    "contract_number": "ZEN-ABC123",
    "identity_role": "customer"
  }
}

Env

Business OS:

MCV_ZENIFY_SYNC_SECRET=...
MCV_ZENIFY_SYNC_TTL=300
MCV_ZENIFY_MERCHANT_EMAIL=merchant@zenify.cx
MCV_ZENIFY_MERCHANT_NAME="Zenify CX"
MCV_ZENIFY_DEFAULT_PLAN_CODE=zenify-crm
MCV_ZENIFY_DEFAULT_PLAN_NAME="Zenify CRM"
MCV_ZENIFY_DEFAULT_BILLING_INTERVAL_MONTHS=1

Zenify app phải dùng cùng MCV_ZENIFY_SYNC_SECRET để ký payload.

Nguyên Tắc Vận Hành

• Zenify không tự trở thành identity source. User profile cập nhật ở Business OS.
• Zenify signup sync là idempotent: gọi lại cùng source_id không tạo trùng account/hợp đồng.
• Billing cycle chỉ sinh khi payload có recurring_amount_vnd lớn hơn 0.
• Khi cần revenue share hoặc payout riêng cho từng merchant, thêm provider_account_id vào service_contracts thay vì tách Zenify sang database độc lập.

English Summary

Zenify is modeled as a merchant in MCV Business OS. Every Zenify signup is pushed to app.mcv.network through an HMAC-signed endpoint, where Business OS upserts the user, customer account, Zenify merchant account, service contract and external source mapping. Zenify remains the CRM runtime, while Business OS owns identity, billing and customer master data.