Clover inventory price sync (webhook)

Clover inventory price sync (webhook)

IndochinaPOS can listen for Clover Inventory webhook events and update local catalog prices for products whose sku_code equals the Clover item ID (same mapping as Import Clover Excel).

Prerequisites

• Products imported from Clover (or manually set sku_code = Clover item ID).
• Clover app with Read inventory permission on the merchant.
• Public HTTPS API base URL on the server (PUBLIC_API_BASE_URL or APP_URL).

Webhook URL

Single endpoint for all stores:

{PUBLIC_API_BASE_URL}/api/v1/integrations/clover/webhook

Example: https://api.example.com/api/v1/integrations/clover/webhook

The vendor Store configuration → General tab shows this URL when the env var is set.

Clover Developer Dashboard

Follow Clover — Use webhooks:

1. App Settings → Webhooks — paste the callback URL above (HTTPS only).
2. Send Verification Code — Clover POSTs { "verificationCode": "…" }; the backend responds 200 OK (code is logged server-side).
3. Paste the verification code in the dashboard and Verify.
4. Subscribe to Inventory events (object key I).
5. Copy the Clover Auth Code shown after verification (sent as header X-Clover-Auth on each notification).

Store configuration (vendor dashboard)

On Stores → Configuration → General → Clover price sync:

Field	Purpose
Merchant ID (mId)	Must match the merchant key in webhook payloads
API environment	Sandbox vs production Clover API host
Enable price sync	Gate processing for this store
Clover Auth Code	Must match X-Clover-Auth
API access token	Used to GET /v3/merchants/{mId}/items/{itemId} after each webhook

Save the section after changing secrets.

Runtime behavior

• Webhook payload chỉ có objectId (ví dụ I:GHIVJT2ABCRSC) — backend gọi GET /v3/merchants/{mId}/items/{itemId} để lấy item hiện tại (tên, giá cents, sku, …).
• Log server: Clover item fetched … name=… price=… và response webhook { ok: true, sync: { details: [{ remoteItem, priceDecimal, localMatches, outcome }] } }.
• Matching items rows for the store (store_id + sku_code) update price and default variation price when applicable.
• DELETE inventory events are ignored (price sync only).
• Price changes are recorded in items_selling_price_history with automated actor id 0.

Tests

• clover-webhook-payload.util.spec.ts
• clover-webhook.service.spec.ts
• clover-inventory-price-sync.service.spec.ts
• vendor-store-configuration.service.spec.ts (Clover PATCH)
• vendor-store-configuration-sections.spec.ts (Clover section PATCH)