WooCommerce Integration

وقتی «وصل شد» هنوز به معنی «درست یکپارچه شد» نیست

فرض کن دو فروشگاه WooCommerce داری. هر دو endpoint سفارش می‌دهند، اما یکی افزونه‌ای نصب کرده که status و meta field جدید می‌سازد. در همان زمان یک webhook بعد از timeout دوباره ارسال می‌شود. اگر connector فقط payload را بگیرد و status را مستقیم داخل state داخلی بنویسد، چند سؤال حیاتی بی‌پاسخ می‌ماند: این پیام واقعاً از همان فروشگاه آمده؟ کلید API چه سطح دسترسی دارد؟ retry همان event قبلی است یا event جدید؟ status سفارشی چه معنایی دارد؟ و آیا mapping این سایت با سایت دیگر یکسان است؟

خروجی این درس WooCommerce Connector Contract and Webhook Ledger v1 است. هدف «ساختن یک WooCommerce client» نیست؛ هدف این است که هر promotion از WooCommerce به مدل داخلی از evidence قابل‌بازسازی عبور کند.

مرز مالکیت COM-028

COM-028 فقط integration اختصاصی WooCommerce را مالک است: site identity، REST surface، credential scope، order/status mapping، webhook verification، delivery evidence، extension isolation و reconciliation. COM-029 معماری generic connector را مالک است و COM-027 integration اختصاصی Shopify را.

سه خط قرمز:

1. WooCommerce status != canonical state
2. valid HMAC != business completion
3. same plugin name on two sites != same contract

مدل ذهنی: Site → REST/Auth → Order observation → Webhook verification → Site adapter → Mapping version → Dedupe/Reconcile → Canonical promotion

مسیر قابل‌ممیزی:

site_ref → wc/v3 + credential_scope → order_id/order_key_ref/created_via/wc_status → webhook_id/topic/status → signature_check + payload_digest + delivery_attempt → custom namespace + extension assumption → mapping_version → reconciliation_state → canonical_order_state → evidence_ref

هر مرحله failure متفاوتی دارد. مشکل signature را با mapping حل نمی‌کنیم؛ custom status را با اضافه‌کردن همان رشته به مدل داخلی حل نمی‌کنیم؛ و retry را با «احتمالاً همان قبلی است» نمی‌بندیم.

FACT، INFERENCE و DESIGN را جدا نگه دار

FACT: مستندات فعلی WooCommerce، REST API v3 را نسخه جاری و توصیه‌شده برای integrationهای جدید معرفی می‌کنند و مسیرهای wc/v3 شامل Orders هستند.

FACT: REST API key به یک WordPress user و سطح دسترسی read، write یا read_write متصل می‌شود. در HTTPS، WooCommerce استفاده از Consumer Key/Secret برای Basic Auth را مستند کرده است.

FACT: webhook در WooCommerce topic، status، delivery URL و secret دارد؛ secret برای ساخت HMAC-SHA256 از body استفاده می‌شود و signature در header ارسال می‌شود. Headerهای webhook شامل ID و Delivery ID هم هستند.

INFERENCE: چون siteها می‌توانند افزونه، status، field و workflow متفاوت داشته باشند، contract مؤثر دو فروشگاه لزوماً یکی نیست؛ بنابراین assumptionهای plugin/site باید versioned و scoped باشند.

DESIGN: MAKNOW هر observation WooCommerce را قبل از canonical promotion از mapping، signature evidence، site namespace و reconciliation عبور می‌دهد. این policy محلی است، نه الزام WooCommerce.

قرارداد ۲۲بُعدی WooCommerce

Gate 1 — connector و site را صریح هویت بده

connector_id و site_ref باید نشان دهند این evidence مربوط به کدام فروشگاه و کدام adapter است. «WooCommerce production» هویت کافی نیست.

Gate 2 — REST surface را pin کن

rest_api_version باید صریح باشد. برای integration جدید این درس baseline را روی wc/v3 می‌گذارد. endpoint بودن به‌تنهایی کافی نیست؛ version بخشی از contract است.

Gate 3 — credential scope را از credential type جدا کن

وجود Consumer Key/Secret نمی‌گوید این کلید مجاز به read یا write موردنیاز است. credential_scope باید با operation منطبق باشد. secret واقعی داخل artifact ذخیره نمی‌شود؛ فقط reference و scope ثبت می‌شود.

Gate 4 — order identity را از display number جدا کن

order_id، order_key_ref و created_via evidence متفاوتی می‌دهند. order_key_ref باید به شکل reference نگهداری شود، نه اینکه داده حساس/عملیاتی بی‌دلیل در خروجی learner تکثیر شود.

Gate 5 — wc_status فقط observation خارجی است

processing، on-hold یا status سفارشی یک واقعیت WooCommerce هستند. canonical_order_state فقط از mapping versioned می‌آید. raw status نباید مستقیم domain logic را کنترل کند.

Gate 6 — mapping version با تغییر معنا باید عوض شود

اگر plugin status جدیدی مثل awaiting-pickup معرفی کند یا semantics یک meta field عوض شود، mapping_version قبلی دیگر evidence کافی نیست. تا mapping جدید review نشده، نتیجه HOLD_MAPPING_VERSION است.

Gate 7 — webhook را قبل از استفاده verify کن

webhook_id، webhook_topic و webhook_status context پیام را می‌سازند. signature_check باید body دریافت‌شده را با secret مرجع verify کند. signature نامعتبر یا نامعلوم => HOLD_WEBHOOK_SIGNATURE.

Gate 8 — signature فقط authenticity است

HMAC موفق فقط می‌گوید body با secret تنظیم‌شده سازگار است. نمی‌گوید order واقعاً fulfilled شده، canonical state درست است یا event دقیقاً یک‌بار رسیده است.

Gate 9 — payload digest و delivery attempt را ثبت کن

payload_digest و delivery_attempt به تشخیص replay/retry کمک می‌کنند. اگر delivery تکراری دوباره side effect بسازد، connector fail شده حتی اگر هر دو درخواست 2xx باشند.

Gate 10 — extensionها را namespace و site-scope کن

custom_field_namespace و extension_assumption باید نشان دهند کدام plugin/field/status روی کدام site معتبر است. assumption سایت A را بدون revalidation روی سایت B reuse نکن.

Gate 11 — reconciliation قبل از promotion uncertainty را می‌بندد

reconciliation_state مشخص می‌کند event با REST snapshot، event ledger یا روش bounded دیگری بسته شده است. timeout، replay یا status سفارشی بدون reconciliation نباید success تمیز تولید کند.

Gate 12 — evidence ناقص fail-closed است

اگر REST version، credential scope، signature، digest، mapping یا reconciliation evidence نامعلوم است، نتیجه typed HOLD/PARTIAL می‌شود؛ نه اینکه «فعلاً قبول کنیم» و بعداً دنبال علت بگردیم.

مثال‌های کاری

۱. baseline استاندارد → ACCEPT_CONNECTOR

Site A روی wc/v3 است، credential فقط scope لازم را دارد، order observation از REST آمده، webhook فعال است، signature verify شده، digest ثبت شده، mapping version روشن است و reconciliation بسته شده است.

۲. webhook بدون signature معتبر → HOLD_WEBHOOK_SIGNATURE

حتی اگر payload شبیه order واقعی باشد، قبل از verify نباید canonical update تولید کند.

۳. افزونه status جدید اضافه می‌کند ولی mapping همان map-v5 می‌ماند → HOLD_MAPPING_VERSION

Parser ممکن است رشته جدید را بخواند؛ اما معنای canonical هنوز اثبات نشده است.

۴. delivery دوم همان payload را دوباره اعمال می‌کند → HOLD_RECONCILIATION

delivery_attempt=2 و digest یکسان باید trigger dedupe/reconciliation باشد، نه side effect دوم.

۵. assumption سایت A روی سایت B reuse می‌شود → HOLD_EXTENSION_SCOPE

نام plugin یکسان هم guarantee نمی‌کند configuration، نسخه یا field semantics یکسان باشد.

۶. transfer: wc-awaiting-pickup روی یک site جدید

namespace و assumption را برای همان site ثبت کن، mapping را bump کن، webhook evidence و REST snapshot را دوباره reconcile کن. اگر معنای جدید به state موجود قابل نگاشت نیست، HOLD را حفظ کن؛ canonical state machine را فقط برای راحتی adapter گسترش نده.

failure modeهای رایج

• یک Consumer Key با دسترسی بیش‌ازحد برای همه‌ی operationها؛
• ذخیره secret واقعی در config آموزشی یا log؛
• مستقیم نوشتن wc_status در state داخلی؛
• فرض اینکه REST v3 روی همه siteها contract مؤثر یکسان می‌دهد؛
• قبول webhook فقط چون URL/ID درست به نظر می‌رسد؛
• مساوی گرفتن signature معتبر با fulfillment موفق؛
• پردازش دوباره‌ی retry به‌عنوان event جدید؛
• تغییر custom status بدون mapping-version bump؛
• reuse کردن custom-field assumption بین دو site؛
• نداشتن REST pull/reconciliation برای uncertainty؛
• تکثیر بی‌دلیل order key یا داده‌ی مشتری در evidence artifacts؛
• کپی‌کردن تصمیم baseline در transfer بدون recomputation.

گزینه‌ها و trade-offها

REST-only polling: ساده و قابل‌کنترل، ولی latency بیشتر و load بالاتر دارد. برای reconciliation خوب است، نه همیشه برای واکنش سریع.

Webhook-only: latency پایین، اما duplicate/replay/missed delivery و disabled webhook را باید مدیریت کند. بدون reconciliation کافی نیست.

Webhook + bounded REST reconciliation: contract بیشتری می‌خواهد، اما uncertainty را بهتر می‌بندد و pattern ترجیحی این درس است.

Raw WooCommerce model downstream: شروع سریع، coupling شدید به plugin/site semantics.

Versioned site adapter: کار طراحی بیشتری دارد، اما custom status/meta را در مرز site نگه می‌دارد و downstream را پایدارتر می‌کند.

پل برای فرد باتجربه: ۱۶ سؤال review

1. connector_id و site_ref دقیق چیست؟
2. کدام rest_api_version pin شده؟
3. credential برای کدام user/permission scope است؟
4. operation فعلی read است یا write هم لازم دارد؟
5. order_id و order_key_ref چگونه trace می‌شوند؟
6. created_via چه فرضی را تغییر می‌دهد؟
7. wc_status چگونه به canonical state map می‌شود؟
8. چه چیزی mapping-version bump را trigger می‌کند؟
9. webhook topic/status چیست؟
10. signature روی همان raw body چگونه verify شده؟
11. payload digest چیست؟
12. duplicate delivery چگونه تشخیص داده می‌شود؟
13. custom field/status تحت کدام namespace است؟
14. assumption به کدام site/plugin version محدود است؟
15. uncertainty چگونه reconcile می‌شود؟
16. آیا reviewer می‌تواند decision را فقط از evidence_ref بازسازی کند؟

تمرین هدایت‌شده و مستقل

Lab آفلاین ۸ fixture دارد: baseline، signature نامعتبر، custom-status بدون mapping bump، duplicate side effect، cross-site assumption reuse، credential scope ناقص، evidence digest مفقود و transfer صحیح برای custom status.

تمرین مستقل: یک merchant افزونه‌ای نصب می‌کند که status awaiting-pickup و field جدید pickup_slot می‌سازد. adapter را update کن؛ مشخص کن چه چیزهایی site-specific می‌مانند، mapping چه زمانی bump می‌شود، webhook verification و reconciliation چه evidenceی لازم دارند، و چرا baseline سایت دیگر oracle این تصمیم نیست.

evidence قابل‌قبول

Artifact باید هر ۲۲ بُعد را پر کند یا non-success state صریح بدهد. هیچ secret واقعی ذخیره نمی‌شود؛ REST version و scope traceable هستند؛ raw wc_status مستقیم canonical truth نمی‌شود؛ signature قبل از webhook acceptance بررسی می‌شود؛ digest/attempt duplicate behavior را قابل‌ممیزی می‌کنند؛ extension assumption به site محدود است؛ و transfer mapping را مستقل recompute می‌کند.

Lab کاملاً synthetic و offline است؛ network، API key، store واقعی یا customer data لازم ندارد.

Assessment و transfer

برای پایان درس باید بتوانی:

1. مرز COM-028 را در برابر COM-027 و COM-029 توضیح بدهی؛
2. WooCommerce Connector Contract and Webhook Ledger v1 را بسازی؛
3. wc/v3 و credential scope را صریح pin کنی؛
4. authenticity webhook را از business correctness جدا کنی؛
5. custom status را بدون mapping version جدید reject کنی؛
6. duplicate delivery را بدون side effect تکراری reconcile کنی؛
7. extension assumption را site-scoped نگه داری؛
8. transfer یک plugin/status جدید را بدون آلوده‌کردن canonical model بازسازی کنی.

منابع و freshness

• WooCommerce REST API v3 — rechecked در 15 سپتامبر 2026؛ مرجع FACT برای current/recommended REST surface و wc/v3.
• WooCommerce Authentication — rechecked در 15 سپتامبر 2026؛ مرجع FACT برای API key ownership و access level.
• WooCommerce Orders API — rechecked در 15 سپتامبر 2026؛ مرجع FACT برای order fields مثل id، order_key، created_via و status.
• WooCommerce Webhooks — rechecked در 15 سپتامبر 2026؛ مرجع FACT برای topic/status/delivery URL، HMAC-SHA256 signature و delivery headers.
• WooCommerce Order Statuses — rechecked در 15 سپتامبر 2026؛ context فعلی برای core status semantics. Extension isolation و promotion policy در این درس MAKNOW DESIGN هستند.