Integration-ready contract

Mock Shopee Open API

API mô phỏng dùng envelope, HMAC, idempotency, webhook và error injection để PenAI có thể phát triển adapter an toàn trước khi HVN cấp Shopee credentials thật.

Authentication

Mọi endpoint /api/v2/* yêu cầu bốn header:

X-Partner-Id: <partner-id>
X-Shop-Id: hvn-demo-store
X-Timestamp: <unix-seconds>
X-Signature: <hmac-sha256>

Base string: METHOD + newline + PATHNAME + newline + TIMESTAMP + newline + SHA256(rawBody). Timestamp có hiệu lực ±5 phút.

Write safety

Các thao tác thay đổi stock, content hoặc campaign bắt buộc có:

X-Idempotency-Key: approval-<request-id>

Gửi lại cùng key trả cùng response và không thực thi lần hai. Mọi write được lưu audit và phát domain event.

Endpoints

Subset vừa đủ cho các demo workflow đã chọn.

Tải OpenAPI JSON

Webhook delivery

Đăng ký URL qua set_subscription. Simulator gửi event với:

X-HVN-Event-Id: evt_...
X-HVN-Webhook-Signature: HMAC-SHA256(webhook-secret, rawBody)

Delivery timeout 3 giây, tối đa 3 lần thử. Event có eventId và dedupKey để consumer chống xử lý trùng.