Configuration

1. Environment Variables

Core keys come from @venizia/ignis / @nx/core; service-specific keys are in src/common/environments.ts.

Core / Runtime

Name	Type	Default	Required	Description
APP_ENV_SERVER_PORT	number	1190 ⚠️		HTTP listen port (odd vs 310x0 siblings)
APP_ENV_BASE_PATH	string	/v1/api		Route prefix (no per-service segment)
APP_ENV_KAFKA_BROKERS	string	—	✓	Comma-separated brokers
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00150-INVOICE_CONSUMER		Default fallback (${ServiceCodes.INVOICE}_CONSUMER); env sets SVC-00150-INVOICE
APP_ENV_KAFKA_GROUP_ID	string	SVC-00150-INVOICE_CONSUMER_GROUP		Consumer group; env sets SVC-00150-INVOICE-LOCAL
APP_ENV_APPLICATION_TIMEZONE	string	Asia/Ho_Chi_Minh		Cron timezone

BullMQ Redis

Name	Type	Default	Required	Description
APP_ENV_INVOICE_BULLMQ_REDIS_MODE	single|cluster	—		Connection mode
APP_ENV_INVOICE_BULLMQ_REDIS_HOST / _PORT	string/number	—	✓	Single-mode host/port
APP_ENV_INVOICE_BULLMQ_REDIS_PASSWORD / _DATABASE	string/number	—		Auth / db index
APP_ENV_INVOICE_BULLMQ_REDIS_CLUSTER_NODES	string	—		Cluster-mode nodes
APP_ENV_INVOICE_BULLMQ_REDIS_MAX_RETRY	number	—		Connection retry
APP_ENV_INVOICE_ISSUANCE_WORKER_CONCURRENCY	number	10		Issuance worker concurrency (claim-expiry fixed at 3)

Providers & Webhooks

Name	Type	Required	Description
APP_ENV_VNIS_DEFAULT_TAX_CODE / _CLIENT_ID / _CLIENT_SECRET	string	✓	VNIS default connection (seeded into Configuration)
APP_ENV_TVAN_API_KEY	string	✓	T-VAN credential (seeded, encrypted)
APP_ENV_VNPAY_TVAN_NAME / _API_KEY	string		VNPAY T-VAN naming/key
APP_ENV_INVOICE_WEBHOOK_SECRET	string	✓	Merchant→platform webhook (VNPAY/iiapi callback)
APP_ENV_INVOICE_WEBHOOK_INTERNAL_SECRET	string	✓	iiapi/commerce→platform internal webhook (HMAC-SHA256)
APP_ENV_INVOICE_WEBHOOK_CALLBACK_URL / _INTERNAL_BASE_URL	string		Callback URLs
APP_ENV_INVOICE_CREDENTIALS_KEY	string	✓	AES-256-GCM key — exactly 32 bytes / 64 hex (openssl rand -hex 32)
APP_ENV_INVOICE_CLAIM_BASE_URL	string	✓	Buyer self-service claim link base

⚠️ APP_ENV_..._WORKER_ID (snowflake) is not configured — see Operations.

2. Feature Flags

Flag	Source	Default	Description
Scheduled issuance	Configuration row INVOICE_SCHEDULED_ISSUANCE.jValue.enabled	true	Cron batch issuance on/off
Issuance mode	InvoiceProviderConfig.issuanceMode	MANUAL	Per-config: REAL_TIME / MANUAL / SCHEDULED / BUYER_SELF_SERVICE
autoRelease / autoSign / autoSendCqt / isSendMail	InvoiceProviderConfig	false	Per-config export policy

3. Seeded Data

Migration processes in src/migrations/processes/ — idempotent (existence-checked), run via bun run migrate:dev.

File	Seeds	Idempotent
invoice-0001-seed-configurations.ts	3 Configuration rows (VNIS, T-VAN, scheduled issuance)	✓
invoice-0002-seed-webhook-configs.ts	commerce webhook config (INVOICE_COMMERCE_EVENTS → ORGANIZER_HQ_CHANGED)	✓
invoice-0003-seed-permissions.ts	invoice permissions	✓
invoice-0004-seed-role-permissions.ts	role↔permission grants	✓
(VN administrative data)	provinces / wards / administrative units	✓

4. Configuration Storage (Configuration table)

Per-environment runtime configs; credentials AES-256-GCM encrypted via encryptText.

Code	jValue	Credential	Read by
VNIS_DEFAULT_CONNECTION	{ taxCode, provider, clientId }	clientSecret (encrypted)	InvoiceProviderConnectionComponent
TVAN_DEFAULT_CONNECTION	{ provider, name }	apiKey (encrypted)	TVanConnectionComponent
INVOICE_SCHEDULED_ISSUANCE	{ enabled, cronTime: '0 23 * * *', batchSize: 200 }	—	CronComponent / InvoiceScheduledIssuanceService

Per-merchant credentials (InvoiceProvider.password, .webhookSecret) are encrypted on the provider row, not in Configuration.

5. Related Pages

• Operations
• Integration
• Decisions