Integration

1. Service anh em

Direction: → gọi / ← được gọi / ↔ hai chiều.

Anh em	Hướng	Bề mặt	Hợp đồng	Auth	Failure Mode
@nx/sale	←	Kafka PAYMENT_SUCCESS	TSalePaymentSuccess	—	at-least-once; guard khi không COMPLETED / đã có hoá đơn
@nx/commerce	←	Kafka Merchant CDC (Debezium)	TDebeziumMessage<TMerchantPgRow> (metadata.tax)	—	at-least-once; op=u diff-skip
@nx/commerce	←	HTTP webhook /webhooks (callback commerce)	ký HMAC-SHA256	WEBHOOK_INTERNAL_SECRET	từ chối khi chữ ký sai/thiếu
@nx/identity	→	Xác thực JWT qua JWKS	VerifierApplication	JWT (ES256)	từ chối request nếu không xác thực được

2. Hệ thống ngoài

Hai lớp adapter bọc các provider HĐĐT ngoài; enum provider trong DB ánh xạ sang enum iiapi qua InvoiceProviderMapper (src/common/providers.ts).

Hệ thống	Lớp	Hướng	Bề mặt	Auth	Nguồn credential
VNIS	@nx/iiapi	→	phát hành HĐĐT	client id/secret	hàng Configuration core VNIS_DEFAULT_CONNECTION (mã hoá) + mặc định APP_ENV_VNIS_*
VNPAY	@nx/iiapi	↔	phát hành + callback webhook vào	username/password theo từng merchant	hàng InvoiceProvider (mã hoá AES-256-GCM)
T-VAN (provider VNPAY)	@nx/t-van	→	gateway transaction-VAN	API key	hàng Configuration core TVAN_DEFAULT_CONNECTION (credential mã hoá)

Đăng ký adapter (lúc boot):

Component	Đăng ký	Với
InvoiceProviderConnectionComponent	VNIS + client InvoiceProvider theo từng merchant	@nx/iiapi
TVanConnectionComponent	Client T-VAN từ TVAN_DEFAULT_CONNECTION	@nx/t-van

Ánh xạ provider (InvoiceProviderMapper):

DB (InvoiceProviders)	iiapi (IIAPIProviders)
VNPAY	VNPAY

Hiện chỉ có VNPAY trong map DB↔iiapi; toIIAPI/toDB ném lỗi với provider lạ.

3. Luồng xuyên service quan trọng

3.1 Thông tin thuế merchant (MST) — input → TaxInfo có thẩm quyền

Hợp đồng:

• metadata.tax trong commerce là input; TaxInfo (principalType=Merchant) là bản ghi có thẩm quyền.
• Phát hiện thay đổi diff với TaxInfo đã lưu, không phải before-image của Debezium (đúng bất kể REPLICA IDENTITY).
• Frontend đọc relation merchant.taxInfo, không bao giờ metadata.tax.
• op=u chỉ upsert thuế; op=c/r còn tạo profile và (nếu có metadata.eInvoice và merchant đủ điều kiện) một InvoiceProvider VNPAY.

3.2 Phát hành qua adapter provider

Hợp đồng: điều kiện được kiểm soát bởi (businessType, taxMethod) → ALLOWED_INVOICE_TYPES. Mode REAL_TIME / BUYER_SELF_SERVICE yêu cầu TaxMethods.DIRECT.

3.3 Webhook vào

Webhook	Env secret	Xác minh
Callback VNPAY/iiapi (vnpayIIAPICallback)	APP_ENV_INVOICE_WEBHOOK_SECRET	header chữ ký của provider
Callback Commerce (commerceCallback)	APP_ENV_INVOICE_WEBHOOK_INTERNAL_SECRET	HMAC-SHA256 verifyWebhookSignature

4. Độ ổn định hợp đồng

Bề mặt	Độ ổn định	Versioning
HTTP /v1/api/*	ổn định	tiền tố URL /v1/
Kafka PAYMENT_SUCCESS (consume)	ổn định	chỉ thêm trường
Kafka Merchant CDC (consume)	ổn định	envelope Debezium
Adapter iiapi / t-van	bên ngoài	version theo provider (API VNIS/VNPAY/T-VAN)
Webhook /webhooks	ổn định	header chữ ký

5. Trang liên quan

• API Events
• T-VAN Integration — chi tiết tính năng provider
• Decisions