یکپارچه‌سازی سایت؛ از API و Webhook تا Data Contract و Runbook

اتصال موفق این نیست که یک Lead در Demo از فرم سایت به CRM برسد. اتصال موفق وقتی است که همان Lead پس از Retry دوبار ساخته نشود، رضایت ایمیلش گم نشود، شماره ایرانی درست نرمال شود، تغییر Schema جریان را نشکند و اگر CRM چند ساعت قطع شد، تیم بداند چه داده‌ای در صف است و چگونه آن را بدون ارسال تکراری بازیابی کند.

یکپارچه‌سازی سایت یعنی طراحی جریان قابل اعتماد داده و عملیات میان سایت‌ساز و سامانه‌هایی مثل CRM، پرداخت، انبار، حسابداری، ایمیل، پشتیبانی و Analytics. تعداد Appهای Marketplace معیار کافی نیست. باید Source of truth، Data contract، Identity، امنیت، تحویل پیام، خطا، Reconciliation، Observability، هزینه و Exit را برای مهم‌ترین Journeyها اثبات کنید.

یکپارچه‌سازی سایت چیست؟

Integration فقط «اتصال دو ابزار» نیست؛ قرارداد هماهنگی دو یا چند سیستم مستقل است. هر سیستم Data model، Identifier، Permission، Rate limit، Availability، Release cycle و Failure mode خود را دارد. طراحی باید تعیین کند چه رویدادی، با چه معنا و چه ضمانتی از مرز عبور می‌کند.

مثلاً در اتصال فرم Lead به CRM، سایت ممکن است صاحب Submission خام باشد، CRM صاحب Lifecycle فروش و سامانه Email صاحب وضعیت Delivery/Unsubscribe. اگر هر سه «وضعیت مشتری» را مستقل و دوطرفه تغییر دهند، Circular update و داده متناقض محتمل است.

چرا عبارت «دید ۳۶۰ درجه مشتری» خطرناک است؟

هیچ اتصال خودکار تضمین نمی‌کند داده دقیق، کامل یا مجاز است. یک Profile متمرکز می‌تواند رکورد دو فرد را Merge کند، Consent قدیمی را معتبر فرض کند یا Order برگشتی را Revenue موفق بشمارد. به‌جای شعار، سؤال‌های قابل آزمون بپرسید:

• چه Sourceهایی وارد Profile می‌شوند و Purpose هرکدام چیست؟
• Identity چگونه Resolve و Merge/Unmerge می‌شود؟
• Freshness و Quality هر Attribute چگونه نمایش داده می‌شود؟
• چه کسی Access دارد و Retention/Deletion چگونه منتشر می‌شود؟
• Metricهای کسب‌وکار از کدام State نهایی محاسبه می‌شوند؟

برای معماری Event، Identity، Warehouse و Attribution، راهنمای تحلیل داده‌های بازاریابی از GA4 تا Warehouse مکمل این مقاله است.

از Journey و Capability شروع کنید، نه App catalog

فهرست «اتصال به ۵۰۰۰ ابزار» تا زمانی که مسیر واقعی کسب‌وکار را پوشش ندهد ارزش کمی دارد. Journeyهای حیاتی را بنویسید:

Integration inventory؛ نقشه جریان‌ها

برای هر اتصال یک ردیف Versioned ثبت کنید:

Source of truth را به تفکیک Domain تعیین کنید

یک سیستم معمولاً صاحب همه واقعیت‌ها نیست. جدول مالکیت بنویسید:

Source of truth یعنی سیستم مرجع تصمیم، نه تنها محل نگهداری Copy. قواعد Write، Conflict و Correction باید روشن باشند. «همه‌چیز دوطرفه Sync شود» معمولاً چرخه و Last-write-wins ناخواسته می‌سازد.

انواع یکپارچه‌سازی و Trade-off

Native الزاماً امن‌تر یا قابل‌اعتمادتر نیست؛ Marketplace بزرگ نیز کیفیت را تضمین نمی‌کند. برای انتخاب کلی Managed builder، CMS، Headless یا Custom بر اساس TCO و Exit، مقاله انتخاب سایت‌ساز برای کسب‌وکار بزرگ را ببینید.

Sync، Event یا Batch؟

Checkout را نباید به CRM غیرحیاتی Sync وابسته کنید. رویداد Order را Durably ثبت و CRM را Async به‌روز کنید. برعکس، موجودی قابل فروش ممکن است پیش از قبول Order نیاز به تصمیم Sync یا Reservation داشته باشد.

Data contract؛ معنا پیش از JSON

API schema فقط نام Field و Type نیست. Contract باید Semantics را هم مشخص کند:

• Business event و شرط رخداد؛
• شناسه یکتا، Source و Version؛
• Required/optional/null/absent؛
• Enum و Unknown value handling؛
• Timestamp، timezone و ordering؛
• Amount، currency و unit؛
• PII classification، purpose و retention؛
• Error code و retryability؛
• Backward compatibility و deprecation؛
• Sample، test fixture و owner.

OpenAPI Specification می‌تواند Contract HTTP API و Webhookهای ورودی را مستند کند، اما فایل OAS به‌تنهایی رفتار، Permission، Idempotency یا SLO را ثابت نمی‌کند. Documentation را با تست و Evidence زنده نگه دارید.

شناسه و Identity mapping

Email و شماره تلفن Identifier پایدار و یکتای مطمئن نیستند؛ تغییر، اشتراک یا Recycle می‌شوند. برای هر Domain:

• Internal ID پایدار بسازید؛
• External ID هر Provider و Tenant را جدا نگه دارید؛
• Mapping version و source را ثبت کنید؛
• Merge rule، confidence و Human review داشته باشید؛
• Unmerge و Correction را ممکن کنید؛
• Cross-tenant lookup را صریحاً منع و تست کنید.

Upsert بر اساس Email می‌تواند دو مشتری یا دو شعبه را اشتباه یکی کند. Composite key را با Domain و Tenant طراحی کنید.

فارسی، شماره، تاریخ و پول

تبدیل تومان/ریال نباید در چند Connector با Round متفاوت تکرار شود. Owner و Conversion point واحد تعیین کنید.

API versioning و تغییر سازگار

شکستن Integration معمولاً با «به‌روزرسانی موفق» رخ می‌دهد. تغییرها را طبقه‌بندی کنید:

Authentication و Authorization

API key داخل JavaScript مرورگر یا Password اصلی Admin برای Connector، مرز امنی نیست. الگو را بر اساس Actor انتخاب کنید:

• OAuth Authorization Code با محافظت‌های جاری برای دسترسی به نمایندگی کاربر؛
• Client credentials یا Workload identity برای Machine-to-machine، اگر Provider پشتیبانی کند؛
• Token کوتاه‌عمر، Scope/Audience محدود و Rotation؛
• Secret manager، نه تنظیمات قابل مشاهده یا Spreadsheet؛
• Service account جدا برای هر Environment/Integration؛
• Revocation، audit و Break-glass procedure.

RFC 9700 بهترین رویه جاری OAuth ۲.۰ را با تهدیدها و اصلاح الگوهای قدیمی پوشش می‌دهد. وجود OAuth در صفحه Feature کافی نیست؛ Flow، Scope، Redirect URI، Token storage و Revocation را بررسی کنید.

WordPress و Application Password

در WordPress، REST API برای دسترسی External می‌تواند از Application Password استفاده کند تا Password اصلی کاربر داده نشود. مستند Application Passwords در WordPress دامنه و مدیریت آن را توضیح می‌دهد. یک کاربر Service با کمترین Capability، HTTPS، Rotation و Audit بسازید؛ Application Password را در Frontend منتشر نکنید.

Webhook امن و قابل بازیابی

1. Request body خام و Headerهای لازم را بدون تغییر برای Verify آماده کنید.
2. Signature و Timestamp را با Secret درست و Replay window بررسی کنید.
3. Source/Tenant/Event type را Allowlist کنید.
4. Event ID را در Dedup store ثبت کنید.
5. پس از نوشتن Durable در Queue، سریع پاسخ مناسب بدهید.
6. پردازش Business را Async و Idempotent انجام دهید.
7. Retryable و terminal error را جدا کنید.
8. پس از حد Retry، DLQ و Alert بسازید.
9. Replay و Reconciliation را با کنترل Operator فراهم کنید.

هیچ فرض عمومی درباره Exactly-once delivery نکنید. بسیاری از Providerها At-least-once هستند؛ Duplicate و out-of-order را رفتار عادی طراحی کنید. اگر Event فقط اشاره به Resource است، در صورت نیاز State جاری را با API و Version/updated_at بخوانید.

CloudEvents چه کمکی می‌کند؟

CloudEvents قالب مشترکی برای توصیف Event با Attributeهایی مانند ID، Source، Type و Spec version ارائه می‌دهد. این استاندارد Interoperability envelope را بهتر می‌کند؛ Semantics دامنه، ترتیب، Transaction و Delivery guarantee را خودکار حل نمی‌کند.

Idempotency؛ تکرار امن

اگر Client پس از Timeout نداند Order ساخته شده یا نه و Request را دوباره بفرستد، بدون Idempotency دو Order می‌سازد. یک Idempotency key باید به Operation و Caller/Scope وصل و نتیجه قبلی تا Window مناسب نگه داشته شود.

dedupe identity = tenant_id + event_source + event_id

business idempotency = operation + stable_business_key + version

Dedup فقط حذف Event تکراری نیست. Side effectهای Email، Inventory، Invoice و Refund نیز باید دوباره‌پذیر یا Guarded باشند. Key تصادفی تازه در هر Retry، Idempotency نمی‌سازد.

Retry، Backoff و DLQ

Retry نامحدود هزینه و Duplicate می‌سازد. DLQ باید Owner، Reason، payload reference امن، retry count، first/last seen و Action داشته باشد؛ قبرستان پیام نباشد.

Error contract

«خطایی رخ داد» برای Integration قابل اجرا نیست. Error باید Machine-readable code، human summary، occurrence/correlation ID، retryability و Field pointer مناسب داشته باشد، بدون افشای Stack/Secret. RFC 9457 Problem Details for HTTP APIs یک مدل استاندارد برای جزئیات خطای HTTP ارائه می‌دهد؛ Error taxonomy دامنه خود را نیز مستند کنید.

Reconciliation؛ شبکه حقیقت کامل نیست

حتی Webhook خوب ممکن است به‌دلیل Outage، Bug، Retention یا Misconfiguration از دست برود. Job آشتی‌سازی بسازید:

1. Watermark آخرین Sync موفق و Overlap window را نگه دارید.
2. منبع را با Pagination کامل بخوانید.
3. Record count، checksum یا Domain totals را مقایسه کنید.
4. Missing، duplicate، stale و conflicting را دسته‌بندی کنید.
5. Repair را Idempotent و Audit شده اجرا کنید.
6. Drift rate و Age را به SLO وصل کنید.

برای پرداخت، Reconciliation با PSP و Ledger ضروری است؛ Callback تنها منبع حقیقت نیست. طراحی Portfolio و مسیر Settlement/Refund در راهنمای روش‌های پرداخت فروشگاه اینترنتی آمده است.

امنیت API و مصرف داده ثالث

Integration سطح حمله و Trust boundary تازه می‌سازد. Inventory Endpointها، Tokenها، Webhookها و Data flow را نگه دارید. کنترل‌های کلیدی:

• Object/Function-level authorization و Tenant isolation؛
• Rate/resource limit و Protection از expensive operation؛
• Input validation، output encoding و Schema allowlist؛
• SSRF guard برای URL/Callback/Import؛
• Webhook signature، replay control و secret rotation؛
• عدم اعتماد کور به API ثالث؛ validate، sanitize و limit؛
• Dependency/app/vendor inventory و patch/deprecation؛
• Audit trail بدون Token/PII خام.

OWASP API Security Top ۱۰ نسخه ۲۰۲۳ خطر «Unsafe Consumption of APIs» را نیز برجسته می‌کند. Threat model و کنترل‌های عمیق در راهنمای امنیت API، OAuth و Webhook آمده است.

حریم خصوصی و Consent propagation

Server-side Integration نیاز Consent و Purpose را حذف نمی‌کند. برای هر Field مشخص کنید چرا منتقل می‌شود، گیرنده/زیرپردازشگر کیست، کجا نگه‌داری می‌شود، چه مدت و چگونه اصلاح/حذف می‌شود.

Unsubscribe نباید از CRM دوباره با Sync دوطرفه فعال شود. Consent و Deliverability را با راهنمای ایمیل مارکتینگ Permission-based طراحی کنید.

Performance و Frontend integration

Plugin و App لزوماً همه کد خود را در Frontend تزریق نمی‌کند و Direct API هم لزوماً سریع نیست. اثر را اندازه بگیرید:

• JavaScript bytes/parse/eval و Main-thread work؛
• Third-party request، DNS/TLS و failure blocking؛
• Layout shift و Interaction delay؛
• Tag duplication و چند Analytics collector؛
• Cookie/storage و Consent timing؛
• Server call latency، timeout budget و connection pool؛
• Webhook backlog و batch processing.

Widget غیرحیاتی نباید Checkout را Block کند. Circuit breaker و timeout/fallback را بر اساس Criticality طراحی کنید؛ «افزونه بیشتر = سایت کندتر» قانون خطی نیست.

Observability و SLO اتصال

Correlation ID و Trace context را میان Gateway، Queue، Worker و Vendor log منتقل کنید، با Redaction. W3C Trace Context قالب استاندارد انتشار Context trace را تعریف می‌کند. طراحی Metric/Log/Trace/SLO و Alert در مقاله Observability سایت تکمیل شده است.

Testing؛ Sandbox کافی نیست

Test data باید غیرحساس و قابل پاک‌سازی باشد. Production replay را روی Sandbox بدون Anonymization نریزید.

Release، Migration و Rollback

1. Contract version و Consumerها را Inventory کنید.
2. Backward-compatible change را اول منتشر کنید.
3. Dual-read یا Shadow mode برای مقایسه بگذارید.
4. Canary با Tenant/Traffic محدود اجرا کنید.
5. Reconciliation و Business guardrail را ببینید.
6. Cutover و deprecation را تاریخ‌دار کنید.
7. Rollback را برای Code، Schema، Queue و Side effect تعریف کنید.
8. پس از تثبیت، Secret/Endpoint قدیمی را حذف کنید.

Build once، Progressive delivery، Verification و Rollback در راهنمای CI/CD امن توضیح داده شده است.

ارزیابی قابلیت Integration سایت‌ساز

به جای «دارد/ندارد»، سه Use case حیاتی را در PoC اجرا و Failure را عمداً تزریق کنید. Demo موفق بدون Duplicate/Retry/Exit evidence امتیاز کامل نمی‌گیرد.

Native، iPaaS یا Custom؟

Custom کنترل بیشتر می‌دهد، نه نتیجه رایگان. اگر تیم On-call، تست و نگهداری ندارد، اتصال سفارشی پرریسک می‌شود. iPaaS نیز Operations را حذف نمی‌کند؛ فقط بخشی از Runtime را منتقل می‌کند.

TCO Integration

3-year integration TCO = platform/app/iPaaS licenses and task overage
                       + build/config/mapping/migration
                       + test/sandbox/environment
                       + monitoring/log/storage/egress
                       + security/privacy/compliance assurance
                       + maintenance/version/deprecation work
                       + incident/support/on-call cost
                       + exit/rebuild/data export

هزینه هر Task در Flow چندمرحله‌ای، Burst، Retry و Replay را سناریو کنید. Connector ارزان با Error opaque و بدون Export می‌تواند Incident و Exit گران‌تری داشته باشد.

نمونه ۱: فرم فارسی تا CRM و ایمیل

1. Form یک submission_id پایدار و policy/consent version می‌سازد.
2. Phone را به فرم Canonical تبدیل و مقدار خام را فقط در صورت نیاز/Policy نگه می‌دارد.
3. Submission در Store/Queue پایدار ثبت می‌شود؛ موفقیت UI به CRM زنده وابسته نیست.
4. Worker با External mapping و Idempotency، Contact/Lead را می‌سازد یا به‌روز می‌کند.
5. Duplicate احتمالی quarantine یا طبق Rule دارای confidence Merge می‌شود.
6. Subscription فقط با Consent مناسب به ESP می‌رود.
7. CRM owner و status اولیه را برمی‌گرداند؛ Site از CRM حقیقت Sales stage نمی‌سازد.
8. Job آشتی‌سازی Submissionهای بدون Lead و Leadهای بدون Source را گزارش می‌کند.

نمونه ۲: سفارش، پرداخت، موجودی و حسابداری

برای فروشگاه ایرانی، Order ID، Payment attempt ID، PSP reference، SKU/variant و Accounting document ID را جدا نگه دارید. Flow:

1. Site یک Order draft و Payment attempt یکتا می‌سازد.
2. Callback/return مرورگر را تنها حقیقت پرداخت نمی‌داند؛ Server verification می‌کند.
3. Transition پرداخت Idempotent است و Order را دوبار Paid نمی‌کند.
4. OMS Inventory را Reserve و نتیجه را با Version ثبت می‌کند.
5. Event paid به Queue می‌رود؛ WMS/Email/Accounting مستقل مصرف می‌کنند.
6. شکست Accounting Checkout را Rollback نمی‌کند؛ DLQ و Reconcile دارد.
7. Refund با reference جدید و Link به Original payment ثبت و به Ledger آشتی می‌شود.

Available-to-promise، Fulfillment و Return state در راهنمای مدیریت موجودی و ارسال فروشگاه آمده است.

ملاحظات ایران

• Eligibility: Country/entity/KYC و Terms هر SaaS، Marketplace و Payment provider را با شخصیت واقعی بررسی کنید؛ هویت/کشور جعلی راهکار نیست.
• Availability: دسترسی ISP، محدودیت شبکه، DNS/CDN و مسیر Admin/Support را از چند اپراتور تست کنید.
• Payment: Callback، Settlement، Refund، تعطیلی بانکی و Reconciliation داخلی را PoC کنید.
• SMS: Delivery report، خط خدماتی/تبلیغاتی، Unicode، Template و Failover Provider را بسنجید.
• Locale: RTL، ی/ک، اعداد، ‎+۹۸، ریال/تومان، تقویم و timezone را در Data contract بیاورید.
• Cost: ارز، اعتبار Quote، Tax، task/egress و تمدید را با Scenario محاسبه کنید.
• Exit: Export محلی دوره‌ای و مسیر جایگزین برای قطع حساب/پرداخت/Support داشته باشید.

Runbookهای ضروری

Webhook backlog یا DLQ رشد می‌کند

Ingress و Queue را از Consumer جدا بررسی کنید؛ Event age، type، tenant، error class و deploy را Segment کنید. پردازش را با Rate امن مهار، terminalها را quarantine، fix را Canary و Replay را Idempotent اجرا کنید.

Token یا Secret منقضی/افشا شده

Connector را محدود، Token را revoke/rotate، Scope و log access را بررسی، Window رخداد و درخواست‌های مشکوک را استخراج و Secret overlap را کنترل کنید. Password اصلی Admin را جایگزین سریع نکنید.

داده CRM و سایت Drift کرده است

Source ownership، last successful watermark، mapping version و change log را ببینید. Diff را به missing/stale/conflict/duplicate تقسیم، repair را dry-run و Correction را Audit کنید؛ Blind two-way sync نزنید.

Provider rate limit را کاهش می‌دهد

Traffic budget، burst، retry storm و endpoint mix را محاسبه؛ batching/cache/coalescing و backpressure را فعال؛ کار غیرحیاتی را عقب بیندازید و سقف/قرارداد را مذاکره کنید.

Schema یا App update جریان را شکست

Breaking field/enum/auth/signature را با contract diff پیدا، version قدیم را در صورت امکان نگه، Adapter را Fix و تست fixture/Replay را اجرا کنید. سپس Deprecation monitor و CI gate اضافه کنید.

برنامه ۳۰، ۶۰ و ۹۰ روزه

چک‌لیست انتخاب و انتشار

• آیا Journey و Outcome پیش از انتخاب Connector مشخص‌اند؟
• آیا Source of truth و جهت Write برای هر Domain روشن است؟
• آیا ID، Schema، Time، Currency، Error و Version Contract دارند؟
• آیا Auth/Scope/Secret/Revocation و Tenant isolation تست شده‌اند؟
• آیا Duplicate، out-of-order، timeout، ۴۲۹ و partial failure پوشش دارند؟
• آیا Queue، DLQ، Replay و Reconciliation Owner دارند؟
• آیا Consent، Retention، deletion و Vendor exit منتشر می‌شوند؟
• آیا SLI/SLO، Trace/Correlation، Alert و Runbook وجود دارد؟
• آیا ایران با Payment/SMS/Locale/Network/Eligibility/FX تست شده است؟
• آیا TCO سه‌ساله و Export/Replacement path اثبات شده‌اند؟

جمع‌بندی

یکپارچه‌سازی خوب سایت را «مرکز فرماندهی» نمی‌کند؛ هر سیستم را در نقش درست و با مرز قابل مشاهده نگه می‌دارد. Data باید صاحب، معنا و نسخه داشته باشد؛ پیام باید تکرار و بی‌نظمی را تحمل کند؛ خطا باید قابل تشخیص و بازیابی باشد؛ و تیم باید بتواند بدون حدس Drift را آشتی دهد یا Vendor را جایگزین کند.

برای ارزیابی یک سایت‌ساز، از فروشنده نپرسید «چند Integration دارید؟» سه Journey حیاتی خود را با Failure case بدهید و Evidence بخواهید: Source of truth، Auth، Rate limit، Webhook delivery، Replay، Log، Export، TCO و Exit. پاسخ این آزمون از اندازه App store مهم‌تر است.

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

یکپارچه‌سازی Native بهتر است یا API سفارشی؟

به Criticality و Contract بستگی دارد. Native برای Use case استاندارد و تیم کوچک می‌تواند سریع‌تر باشد؛ API سفارشی کنترل بیشتری بر Mapping، State و Operations می‌دهد اما هزینه ساخت/نگهداری دارد. هر دو را با Auth، coverage، retry، reconciliation، SLO، TCO و Exit بسنجید.

آیا Zapier یا ابزار iPaaS برای Integration کافی است؟

برای Flow کم‌ریسک، حجم محدود و Prototype ممکن است کافی باشد. برای Payment، Inventory یا Order حیاتی باید رفتار Duplicate، Retry/DLQ، Rate limit، data residency، Observability، Reconciliation، task cost و Export را اثبات کنید. No-code به معنی No-operations نیست.

Webhook چه تفاوتی با API دارد؟

API معمولاً توسط Consumer برای Request/Query فراخوانی می‌شود؛ Webhook یک HTTP callback است که Producer هنگام رخداد به Consumer می‌فرستد. Webhook نیز API است و به Signature، Replay control، Idempotency، Queue، Retry/DLQ و Reconciliation نیاز دارد.

چرا داده در دو سیستم یکسان نمی‌ماند؟

Source ownership مبهم، Mapping متفاوت، Event گم/تکراری، ترتیب نادرست، تغییر Schema، Identity merge، Rate limit یا اصلاح دستی می‌تواند Drift بسازد. Watermark، Version، idempotency و Job آشتی‌سازی لازم‌اند؛ Sync دوطرفه کور مشکل را تشدید می‌کند.

چطور Integration سایت‌ساز را پیش از خرید تست کنیم؟

سه Journey واقعی را در PoC اجرا کنید و فقط Happy path را نبینید: Duplicate، timeout، ۴۲۹، token rotation، schema change، vendor outage، deletion و export را آزمایش کنید. API coverage، Webhook history/replay، logs، SLO، TCO و مسیر Exit را با Evidence ثبت کنید.