لنفرض أن لديك شركة برمجيات فيها تسعة أشخاص، تبني أنظمة للمستشفيات والجامعات وشركات النقل، وكل مبيعاتها في جدول بيانات مشترك يعدله ثلاثة أشخاص. وفي اجتماع نهاية الشهر سأل المؤسس سؤالاً بسيطاً: كم نتوقع أن نوقع في ديسمبر؟ فأجاب مدير المبيعات بمليون ونصف، وأجاب الشريك الآخر بستمائة ألف، وكلاهما قرأ نفس الجدول. وفي نفس الأسبوع اكتشفت المحاسبة أن الشركة فازت بعقد نظام حجز المواعيد قبل عشرة أيام، ولم يخبرها أحد لكي تصدر الفاتورة الأولى. فقرر الفريق أن ينقل المبيعات إلى نظام CRM على سيرفر الشركة، بشرطين: أن يعطي رقماً واحداً للتوقع يفهم الجميع من أين جاء، وأن تعرف المحاسبة بالفوز في نفس اللحظة دون أن يرسل أحد بريداً. وهذا الدليل يتبع الفريق في الطريق كاملاً.
في مقارنة أدوات إدارة علاقات العملاء CRM وجدنا أن Twenty أحدث الأنظمة مفتوحة المصدر Open Source في الواجهة والـ API، وأن العربية فيه تعمل من اليمين إلى اليسار في أغلب الشاشات، ووجدنا أيضاً أنه نظام CRM فقط بلا فواتير ولا مخزون، فيحتاج أن يتكلم مع غيره. وفي هذا الدليل سوف نشغله على سيرفرنا ونبني عليه مسار بيع Sales Pipeline كما يستخدمه فريق مبيعات صغير في شركة تقنية: مراحل بأسماء عربية، وشركات وجهات اتصال عربية نستوردها من ملف، وصفقات بالريال، ثم توقع للإيرادات Forecast نحسبه من الـ API، وإشعار يصل إلى نظام الفوترة Billing كلما تغيرت مرحلة صفقة.
المواضيع في السلسلة:
- المبيعات B2B للتقنيين: من العميل المحتمل Lead إلى العقد
- مسار البيع Sales Pipeline: المراحل والتوقعات Forecast
- إدارة علاقات العملاء CRM: Salesforce وبدائله مفتوحة المصدر
- CRM على سيرفرك مع Twenty: مسار بيع كامل (الموضوع الحالي)
دليلإدارة علاقات العملاء CRM: Salesforce وبدائله مفتوحة المصدركيف تختار نظام CRM لفريق مبيعاتك: أربعة أسئلة، ومقارنة العربية والأسعار، وتكلفة فريق من خمسة في السنة.
دليلمسار البيع Sales Pipeline: المراحل والتوقعات Forecastكيف تقسم صفقاتك إلى مراحل واضحة وتحسب توقع الإيرادات بالآلة الحاسبة، مع مثال محسوب خطوة بخطوة.
دليلالمبيعات B2B للتقنيين: من العميل المحتمل إلى العقدكيف تبيع شركة تقنية لشركات أخرى: من يقرر عند العميل، وكيف تؤهل الصفقة، وما الوثائق والتسعير من أول اجتماع إلى الفاتورة.وسوف نناقش في هذا المقال ما يلي:
- نشغل Twenty بملف Compose واحد فيه server وworker وPostgreSQL وRedis، بإصدارات مثبتة.
- ننشئ مساحة العمل Workspace ونحول الواجهة إلى العربية ونرى ما يعمل وما لا يعمل فيها.
- نغير مراحل الفرص Opportunities إلى مراحل بيع B2B، ونرى ماذا يحدث للوحة Kanban إذا غيرناها من الـ API.
- نستورد ست شركات من ملف CSV، ونضيف جهات الاتصال والصفقات بسكربت عبر REST API.
- نحسب توقعاً موزوناً Weighted Forecast لكل شهر من بيانات الصفقات.
- نرسل تغييرات الصفقات إلى نظام آخر عبر Webhook موقع بتوقيع HMAC، ونرى لماذا لا يصل الطلب في المحاولة الأولى.
- نحسب أوزان المراحل من تاريخ الصفقات المغلقة بدلاً من أرقام نخمنها، ونرى كم يتغير التوقع، وكم هو هش أمام صفقة واحدة.
- نختبر المستقبل بطلبات موقعة مكررة وقديمة، ونرى أن التوقيع وحده لا يمنع فاتورة مكررة، ثم نصلحه.
- النسخ الاحتياطي Backup والاستعادة والتحديث والمشكلات التي ظهرت لنا.
- ماذا يحدث عندما يتغير شيء، وقائمة تحقق قبل أن يعتمد الفريق على النظام.
والصورة التالية تبين ما سوف نبنيه:

المتطلبات
- سيرفر Linux عليه Docker وDocker Compose، وقد اختبرنا على Docker Engine 29.8.0.
- ذاكرة: التوثيق الرسمي يطلب 2 جيجابايت على الأقل، وبعد انتهاء التجربة كان server يستهلك 922 ميجابايت والـ worker يستهلك 768 ميجابايت وقاعدة البيانات Database 129 ميجابايت، أي حوالي 1.8 جيجابايت للنظام وحده، لذلك خطط لسيرفر بذاكرة 4 جيجابايت إذا كان عليه شيء آخر.
- مساحة: الـ Docker Image الخاصة بالإصدار v2.51.0 حجمها 1.65 جيجابايت بعد فك الضغط.
- طريقة وصول خاصة للفريق، مثل شبكة WireGuard، أو نطاق فرعي Subdomain مثل
crm.example.comخلف Reverse Proxy، وسوف نشرح السبب في قسم الوصول من خارج السيرفر.
التثبيت بملف Compose
المشروع ينشر ملف Compose رسمياً يستخدم الوسم latest افتراضياً، وهذا غير مناسب لنظام فيه بيانات العملاء، والسبب أن الـ server يشغل ترحيل قاعدة البيانات Migration تلقائياً عند كل تشغيل، فإذا سحبت latest بعد شهر فقد ترقى النظام دون أن تأخذ نسخة احتياطية. لذلك بنينا الملف التالي على الملف الرسمي مع تثبيت كل الإصدارات. نبدأ بالمجلد وملف .env:
mkdir -p /opt/crm && cd /opt/crm
cat > .env <<EOF
SERVER_URL=http://localhost:3000
PG_PASSWORD=$(openssl rand -hex 24)
ENCRYPTION_KEY=$(openssl rand -base64 32)
WEBHOOK_SECRET=$(openssl rand -hex 32)
EOF
chmod 600 .envلاحظ أن PG_PASSWORD بالصيغة الست عشرية Hex وليس Base64، والسبب أنها تدخل كما هي داخل رابط الاتصال PG_DATABASE_URL، والرموز / و+ التي تظهر في Base64 تفسد الرابط. أما ENCRYPTION_KEY فهو المفتاح الذي يشفر به Twenty الأسرار المخزنة في قاعدة البيانات، مثل توكنات الحسابات المرتبطة، فاحفظه مع النسخة الاحتياطية، لأن قاعدة بيانات بدون مفتاحها لا تفيدك في الاستعادة. ثم الملف compose.yaml:
name: crm
x-env: &env
PG_DATABASE_URL: postgres://twenty:${PG_PASSWORD}@db:5432/twenty
SERVER_URL: ${SERVER_URL}
REDIS_URL: redis://redis:6379
STORAGE_TYPE: local
ENCRYPTION_KEY: ${ENCRYPTION_KEY}
# Private hosts that webhooks and workflow HTTP calls may reach (SSRF protection blocks the rest)
OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS: hook.example.com
services:
server:
image: twentycrm/twenty:v2.51.0
ports:
- "127.0.0.1:3000:3000"
volumes:
- server-data:/app/packages/twenty-server/.local-storage
environment:
<<: *env
NODE_PORT: 3000
depends_on:
db: { condition: service_healthy }
redis: { condition: service_healthy }
healthcheck:
test: curl --fail http://localhost:3000/healthz
start_period: 15m
interval: 5s
timeout: 5s
retries: 30
restart: unless-stopped
worker:
image: twentycrm/twenty:v2.51.0
command: ["yarn", "worker:prod"]
volumes:
- server-data:/app/packages/twenty-server/.local-storage
environment:
<<: *env
DISABLE_DB_MIGRATIONS: "true"
DISABLE_CRON_JOBS_REGISTRATION: "true"
depends_on:
server: { condition: service_healthy }
restart: unless-stopped
db:
image: postgres:16.15
volumes:
- db-data:/var/lib/postgresql/data
environment:
POSTGRES_DB: twenty
POSTGRES_USER: twenty
POSTGRES_PASSWORD: ${PG_PASSWORD}
healthcheck:
test: pg_isready -U twenty -d twenty
interval: 5s
timeout: 5s
retries: 10
restart: unless-stopped
redis:
image: redis:7.2.16
command: ["--maxmemory-policy", "noeviction"]
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 5s
retries: 10
restart: unless-stopped
hook:
image: node:24.22.1-bookworm
command: ["node", "/hook.js"]
volumes:
- ./hook.js:/hook.js:ro
environment:
WEBHOOK_SECRET: ${WEBHOOK_SECRET}
networks:
default:
aliases: [hook.example.com]
restart: unless-stopped
volumes:
db-data:
server-data:في الإعداد أعلاه لاحظ التالي:
- الـ server هو الذي يشغل ترحيل قاعدة البيانات عند التشغيل، والـ worker يعطل ذلك بالمتغيرين
DISABLE_DB_MIGRATIONSوDISABLE_CRON_JOBS_REGISTRATION، لكي لا يحاول الاثنان تعديل قاعدة البيانات في نفس اللحظة. والـ worker هو من يرسل الـ Webhooks وينفذ المهام الخلفية، فإذا توقف تتوقف الإشعارات دون أن تلاحظ ذلك في الواجهة. - Redis بالسياسة
noevictionكما في الملف الرسمي، والسبب أنه يحمل طابور المهام Queue، ولا تريد أن يحذف Redis مهمة لم تنفذ لأنه احتاج ذاكرة. - أضفنا
start_period: 15mإلى فحص الصحة Health Check، وهذا غير موجود في الملف الرسمي، وسوف نرى السبب بعد قليل. - الخدمة
hookليست جزءاً من Twenty، وإنما سيرفر صغير يمثل نظام الفوترة الذي يستقبل الـ Webhook، وأعطيناه اسماً إضافياً Alias هوhook.example.comداخل شبكة Docker، وسوف نشرح في قسم الـ Webhook لماذا يحتاج اسماً فيه نقطة، ولماذا يحتاج المتغيرOUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS. - المنفذ منشور على
127.0.0.1فقط، فلا يصل إلى النظام أحد من خارج السيرفر إلا عبر الطريقة التي تختارها.
أنشئ الملف hook.js كما في قسم الـ Webhook، أو احذف الخدمة hook إذا لم تكن تحتاجها الآن، ثم شغل النظام وتابع السجلات Logs:
docker compose up -d
docker compose logs -f serverوعند التشغيل الأول سوف تجد أن الـ server يبدأ بالرسالة Running database setup and migrations... ثم يمر على مئات أوامر الترحيل، وفي تجربتنا مرت عشر دقائق تقريباً بين بدء الـ Container والرسالة التالية التي تعني أن النظام جاهز:
LOG [NestApplication] Nest application successfully startedوهنا يظهر سبب start_period، فالملف الرسمي يعطي فحص الصحة 30 محاولة كل خمس ثوان، أي دقيقتين ونصف، فإذا تأخر الـ server أكثر من ذلك وصفه Docker بأنه غير سليم Unhealthy، وفشل docker compose up برسالة dependency failed to start: container ... is unhealthy ولم يبدأ الـ worker أصلاً. وهذا ما حدث لنا في المرة الأولى، وتكرر عند كل إعادة إنشاء للـ Container، حيث استغرق التشغيل الثاني ثماني دقائق، وأغلب الوقت في إقلاع تطبيق Node.js نفسه أكثر من مرة: مرة لأوامر الترحيل ومرة لأوامر النسخة ومرة للتطبيق. والسرعة تختلف بحسب السيرفر، وكان سيرفرنا Docker Desktop على Windows مشغولاً بتجارب أخرى، لذلك أعط النظام وقتاً كافياً بدلاً من أن تطارد خطأ غير موجود.
الإعداد الأول واللغة العربية
افتح http://localhost:3000 واختر Continue with Email، ثم أدخل البريد وكلمة المرور، فيطلب منك النظام اسم مساحة العمل Workspace، ثم ملفك الشخصي، ثم دعوة الفريق ويمكن تخطيها. وأول ما سوف تلاحظه أن مساحة العمل الجديدة ليست فارغة، ففيها خمس شركات وخمسة أشخاص وست فرص تجريبية بأسماء شركات أمريكية معروفة، فاحذفها قبل أن تبدأ لكي لا تدخل في تقاريرك وتوقعاتك، وقد حذفناها بالـ API كما سيأتي.
بعد ذلك اذهب إلى Settings ثم Experience واختر Arabic من قائمة اللغات، وهي واحدة من أكثر من ثلاثين لغة، فتنقلب الواجهة كلها إلى اليمين:

والترجمة جيدة في أغلب الشاشات، ولكن فيها ما يحتاج مراجعة: إعدادات Experience ترجمت «الخبرة» والمقصود تجربة الاستخدام، وأسماء العروض الافتراضية مثل All Companies بقيت بالإنجليزية، وتنسيق التاريخ في البطاقات بالإنجليزية مثل Oct 25, 2026 حتى بعد تغيير اللغة. وهذه كلها أمور شكلية لا تمنع العمل، والأهم أن النص العربي في الحقول يحفظ ويعرض بترتيب صحيح.
مفتاح الـ API
أغلب ما سوف نفعله بعد ذلك يمر عبر الـ API، وتوثيق الـ API يشرح أن Twenty يولد واجهتين REST وGraphQL من نموذج البيانات نفسه، فأي حقل أو كائن Object تضيفه يظهر فيهما مباشرة. أنشئ المفتاح من Settings ثم Developers ثم Create API Key، واختر له اسماً ودوراً Role، فيظهر المفتاح مرة واحدة فقط، فضعه في متغير بيئة ولا تكتبه في ملف داخل المستودع:
read -s TWENTY_API_KEY && export TWENTY_API_KEY
export TWENTY_URL=http://localhost:3000ولاحظ أن الدور الافتراضي للمفتاح هو Admin، وهذا أكثر مما يحتاجه سكربت يقرأ الصفقات فقط، فإذا كان المفتاح لسكربت تقارير فأنشئ له دوراً بصلاحية القراءة من Settings ثم Roles. وإذا نسيت المفتاح في الطلب فالرد يكون كما يلي:
{"statusCode":403,"messages":["Missing authentication token"],"error":"FORBIDDEN_EXCEPTION"}مراحل البيع Pipeline Stages
الفرص Opportunities في Twenty تأتي بخمس مراحل افتراضية هي New وScreening وMeeting وProposal وCustomer، وهذه أقرب لمسار شركة SaaS تبيع للأفراد، أما البيع للشركات فيحتاج مراحل لها شرط خروج واضح كما شرحنا في مقال مسار البيع. والمرحلة في Twenty حقل من نوع SELECT اسمه stage، فنغير خياراته عبر واجهة البيانات الوصفية Metadata API على المسار /metadata. نجلب أولاً معرف الحقل:
curl -s -H "Authorization: Bearer $TWENTY_API_KEY" -H 'Content-Type: application/json' \
$TWENTY_URL/metadata \
-d '{"query":"{ objects(paging:{first:100}) { edges { node { nameSingular fields(paging:{first:200}) { edges { node { name id } } } } } } }"}' \
| node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{const o=JSON.parse(d).data.objects.edges.map(e=>e.node).find(n=>n.nameSingular==="opportunity");console.log(o.fields.edges.find(f=>f.node.name==="stage").node.id)})'ثم نكتب الخيارات الجديدة في الملف stages.json، ونضع الاسم العربي والإنجليزي معاً في التسمية Label، أما القيمة Value فتبقى بالإنجليزية والحروف الكبيرة لأنها ما يخزن في قاعدة البيانات ويستخدمه الـ API:
{"query":"mutation($id: UUID!, $u: UpdateFieldInput!) { updateOneField(input: {id: $id, update: $u}) { id name options } }",
"variables":{"id":"STAGE_FIELD_ID","u":{"defaultValue":"'QUALIFIED'","options":[
{"label":"عميل مؤهل Qualified","value":"QUALIFIED","color":"sky","position":0},
{"label":"اكتشاف الاحتياج Discovery","value":"DISCOVERY","color":"purple","position":1},
{"label":"عرض فني ومالي Proposal","value":"PROPOSAL","color":"turquoise","position":2},
{"label":"تفاوض Negotiation","value":"NEGOTIATION","color":"orange","position":3},
{"label":"فوز Won","value":"WON","color":"green","position":4},
{"label":"خسارة Lost","value":"LOST","color":"red","position":5}]}}}curl -s -H "Authorization: Bearer $TWENTY_API_KEY" -H 'Content-Type: application/json' \
$TWENTY_URL/metadata --data-binary @stages.jsonنجح الطلب ورجعت الخيارات الست، ولكن عندما فتحنا الفرص في عرض Kanban المسمى «حسب المرحلة» وجدنا الصفحة فارغة تماماً مع أن العداد يقول 8 فرص. والسبب أن كل عمود في لوحة Kanban هو سجل مستقل من نوع مجموعة العرض View Group مرتبط بقيمة من قيم المرحلة، فعندما حذفنا القيم القديمة حذف النظام مجموعاتها، ولم ينشئ مجموعات للقيم الجديدة. لذلك نجلب معرف العرض من نفس الـ Metadata API (الاستعلام Query views ونبحث عن العرض الذي نوعه KANBAN)، ثم ننشئ المجموعات:
{"query":"mutation($inputs: [CreateViewGroupInput!]!) { createManyViewGroups(inputs: $inputs) { fieldValue position } }",
"variables":{"inputs":[
{"viewId":"KANBAN_VIEW_ID","fieldValue":"QUALIFIED","position":0,"isVisible":true},
{"viewId":"KANBAN_VIEW_ID","fieldValue":"DISCOVERY","position":1,"isVisible":true},
{"viewId":"KANBAN_VIEW_ID","fieldValue":"PROPOSAL","position":2,"isVisible":true},
{"viewId":"KANBAN_VIEW_ID","fieldValue":"NEGOTIATION","position":3,"isVisible":true},
{"viewId":"KANBAN_VIEW_ID","fieldValue":"WON","position":4,"isVisible":true},
{"viewId":"KANBAN_VIEW_ID","fieldValue":"LOST","position":5,"isVisible":true}]}}وبعد إعادة تحميل الصفحة ظهرت الأعمدة الست. والقاعدة هنا: إذا غيرت قيم حقل تبنى عليه لوحة Kanban من الـ API، فتحقق من اللوحة بعدها مباشرة، لأن الخطأ لا يظهر في رد الـ API وإنما في شاشة الفريق.
استيراد الشركات من CSV
أغلب الفرق لا تبدأ من الصفر، وإنما من جدول بيانات فيه العملاء الحاليون. جهزنا الملف companies.csv بست شركات وهمية وأسماء نطاقات تحت example.com:
Name,Domain,Employees,City
شركة الواحة للتجارة,https://waha.example.com,120,الرياض
مستشفى النخبة التخصصي,https://nukhba-hospital.example.com,850,جدة
جامعة المستقبل الأهلية,https://mustaqbal-uni.example.com,1400,الدمام
مصنع الرمال للبلاستيك,https://rimal-plastic.example.com,300,الجبيل
مكتب السند للمحاماة,https://sanad-law.example.com,25,الرياض
شركة دروب للنقل,https://duroob.example.com,600,مكة المكرمةوالاستيراد ليس في قائمة الخيارات Options كما قد تتوقع، وإنما في قائمة الأوامر Command Menu (الزر ذو النقاط الثلاث أعلى الصفحة) باسم «استيراد الشركات». وبعد رفع الملف تأتي خطوة مطابقة الأعمدة Column Mapping، وفيها طابق النظام عمود City تلقائياً مع العنوان والمدينة، وبقيت الأعمدة الأخرى نختارها يدوياً:

ولاحظ أمرين: حقل اسم النطاق Domain Name من نوع الروابط Links وله أجزاء، فتختار منها «عنوان URL للرابط»، وعدد الموظفين لا يوجد كحقل في الشركات في هذا الإصدار، فإذا كنت تحتاجه في تقسيم العملاء فأنشئ حقلاً مخصصاً Custom Field من نموذج البيانات قبل الاستيراد. بعد ذلك تأتي خطوة التحقق من البيانات وفيها كل صف قبل الحفظ، ثم تأكيد:

جهات الاتصال والصفقات عبر REST API
الآن نضيف لكل شركة جهة اتصال ثم الصفقات، وهذا ما تفعله عادة عندما تنقل البيانات من نظام قديم أو من نموذج تواصل في موقعك. السكربت التالي seed.mjs يعمل بـ Node.js 22 أو أحدث دون أي مكتبات، ويقرأ الشركات المستوردة بأسمائها ثم يضيف الأشخاص والفرص:
// Adds contacts and deals to Twenty through the REST API.
// TWENTY_URL=http://localhost:3000 TWENTY_API_KEY=... node seed.mjs
const URL = process.env.TWENTY_URL, KEY = process.env.TWENTY_API_KEY;
const api = async (method, path, body) => {
const r = await fetch(`${URL}/rest/${path}`, { method,
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: body && JSON.stringify(body) });
const j = await r.json();
if (!r.ok) throw new Error(`${method} ${path}: ${r.status} ${JSON.stringify(j)}`);
return j.data;
};
// Companies were imported from companies.csv; find them by name
const { companies } = await api('GET', 'companies?limit=50');
const co = Object.fromEntries(companies.map((c) => [c.name, c.id]));
const people = [
['فهد', 'القحطاني', 'مدير تقنية المعلومات', 'شركة الواحة للتجارة', '[email protected]'],
['ريم', 'الشهري', 'مديرة التحول الرقمي', 'مستشفى النخبة التخصصي', '[email protected]'],
['خالد', 'الزهراني', 'عميد تقنية المعلومات', 'جامعة المستقبل الأهلية', '[email protected]'],
['منى', 'الدوسري', 'مديرة المشتريات', 'مصنع الرمال للبلاستيك', '[email protected]'],
['عبدالله', 'السبيعي', 'الشريك المدير', 'مكتب السند للمحاماة', '[email protected]'],
['نوف', 'الحربي', 'مديرة العمليات', 'شركة دروب للنقل', '[email protected]'],
];
const contact = {};
for (const [first, last, title, company, email] of people) {
const p = await api('POST', 'people', { name: { firstName: first, lastName: last }, jobTitle: title,
emails: { primaryEmail: email }, companyId: co[company] });
contact[company] = p.createPerson.id;
}
// name, company, amount in SAR, stage, expected close date
const deals = [
['نظام حجز مواعيد للعيادات', 'مستشفى النخبة التخصصي', 480000, 'NEGOTIATION', '2026-11-20'],
['بوابة الطلاب والدفع الإلكتروني', 'جامعة المستقبل الأهلية', 900000, 'PROPOSAL', '2026-12-15'],
['ربط المتجر الإلكتروني مع ERP', 'شركة الواحة للتجارة', 150000, 'DISCOVERY', '2026-12-30'],
['تطبيق تتبع الشحنات', 'شركة دروب للنقل', 620000, 'QUALIFIED', '2027-01-31'],
['نظام إدارة القضايا', 'مكتب السند للمحاماة', 95000, 'WON', '2026-10-15'],
['لوحة مراقبة خطوط الإنتاج', 'مصنع الرمال للبلاستيك', 210000, 'LOST', '2026-10-10'],
['استضافة وصيانة سنوية', 'شركة الواحة للتجارة', 72000, 'NEGOTIATION', '2026-11-30'],
['مرحلة ثانية: تطبيق المرضى', 'مستشفى النخبة التخصصي', 350000, 'DISCOVERY', '2027-02-28'],
];
for (const [name, company, sar, stage, close] of deals) {
await api('POST', 'opportunities', { name, stage, closeDate: `${close}T09:00:00.000Z`,
amount: { amountMicros: sar * 1_000_000, currencyCode: 'SAR' },
companyId: co[company], pointOfContactId: contact[company] });
}
console.log(`people: ${people.length}, opportunities: ${deals.length}`);node seed.mjsوالمخرج سوف يكون كما يلي:
people: 6, opportunities: 8في السكربت أعلاه لاحظ التالي:
- المبلغ في Twenty حقل من نوع العملة Currency يخزن بوحدة الجزء من المليون
amountMicros، فمبلغ 480 ألف ريال يكتب480000000000، والسبب أن الأعداد الصحيحة لا تفقد الدقة كما تفقدها الكسور العشرية في الحسابات المالية، وقد شرحنا سبب ذلك في مقال الأرقام العشرية من الداخل. - العملة
SARتكتب مع كل مبلغ، فالنظام يسمح بصفقات بعملات مختلفة في نفس المسار، ولكنه لا يحول بينها، فإذا جمعت صفقات بالدولار والريال في تقرير واحد فالتحويل عليك. - السكربت يبحث عن الشركة بالاسم، والاسم ليس فريداً في Twenty، فإذا كان عندك شركتان بنفس الاسم فاستخدم النطاق أو معرفاً خارجياً تضيفه كحقل مخصص.
- حذف البيانات التجريبية التي جاءت مع مساحة العمل يكون بنفس الطريقة:
GETعلىopportunitiesوpeopleوcompaniesثمDELETEلكل معرف.
وهذه لوحة Kanban بعد ذلك، وفي رأس كل عمود مجموع مبالغ الصفقات فيه:

والاتجاه صحيح في اللوحة، ولكن لاحظ أن التسميات التي تجمع العربية والإنجليزية مثل «اكتشاف الاحتياج Discovery» تقص من جهة الكلمة الإنجليزية عندما يضيق العمود، وكذلك التاريخ في البطاقة يقص من أوله. فإذا كان فريقك يعمل بالعربية فقط فاجعل التسمية عربية قصيرة، وأبق القيمة الإنجليزية في الـ API.
وكل تغيير في الصفقة يسجل في الجدول الزمني Timeline الخاص بها، ومن غيرها ومتى، وهذا ما يحتاجه مدير المبيعات عندما يسأل لماذا تأخرت صفقة:

توقع الإيرادات Forecast من الـ API
التوقع الموزون Weighted Forecast يضرب قيمة كل صفقة مفتوحة في احتمال إغلاقها بحسب مرحلتها، ثم يجمعها لكل شهر حسب تاريخ الإغلاق المتوقع، وقد شرحنا طريقته وحدوده في مقال مسار البيع. Twenty يعرض مجموع كل عمود في اللوحة، ولكنه لا يحمل حقلاً للاحتمال في الفرص، لذلك نحسب التوقع خارج النظام بالـ API، وهذا يعطيك حرية تعديل الأوزان دون تغيير نموذج البيانات. السكربت forecast.mjs:
// Weighted pipeline forecast from Twenty opportunities, grouped by expected close month.
// TWENTY_URL=http://localhost:3000 TWENTY_API_KEY=... node forecast.mjs
const WEIGHT = { QUALIFIED: 0.1, DISCOVERY: 0.2, PROPOSAL: 0.4, NEGOTIATION: 0.7, WON: 1, LOST: 0 };
const r = await fetch(`${process.env.TWENTY_URL}/rest/opportunities?limit=200`, {
headers: { Authorization: `Bearer ${process.env.TWENTY_API_KEY}` } });
const { data: { opportunities } } = await r.json();
const months = {};
for (const o of opportunities) {
const m = o.closeDate.slice(0, 7);
const sar = o.amount.amountMicros / 1e6;
const row = (months[m] ??= { open: 0, weighted: 0, won: 0, deals: 0 });
row.deals += 1;
if (o.stage === 'WON') row.won += sar;
else if (o.stage !== 'LOST') { row.open += sar; row.weighted += sar * WEIGHT[o.stage]; }
}
const fmt = (n) => Math.round(n).toLocaleString('en-US').padStart(11);
console.log('month deals open pipeline weighted won');
let t = { open: 0, weighted: 0, won: 0 };
for (const m of Object.keys(months).sort()) {
const x = months[m];
console.log(`${m} ${String(x.deals).padStart(5)} ${fmt(x.open)} ${fmt(x.weighted)} ${fmt(x.won)}`);
t.open += x.open; t.weighted += x.weighted; t.won += x.won;
}
console.log(`total ${fmt(t.open)} ${fmt(t.weighted)} ${fmt(t.won)}`);قبل تشغيله حركنا ثلاث صفقات كما يحدث في أسبوع عمل عادي: فزنا بنظام حجز المواعيد، وانتقلت بوابة الطلاب إلى التفاوض، ورفعنا قيمة ربط المتجر إلى 180 ألفاً بعد اكتشاف الاحتياج وانتقلت إلى العرض. وكل ذلك بطلب PATCH واحد لكل صفقة:
curl -s -X PATCH -H "Authorization: Bearer $TWENTY_API_KEY" -H 'Content-Type: application/json' \
"$TWENTY_URL/rest/opportunities/OPPORTUNITY_ID" \
-d '{"stage":"PROPOSAL","amount":{"amountMicros":180000000000,"currencyCode":"SAR"}}'ثم شغلنا التوقع، والمخرج كان كما يلي:
month deals open pipeline weighted won
2026-10 3 0 0 575,000
2026-11 1 72,000 50,400 0
2026-12 2 1,080,000 702,000 0
2027-01 1 620,000 62,000 0
2027-02 1 350,000 70,000 0
total 2,122,000 884,400 575,000في المخرج أعلاه لاحظ التالي:
- المسار المفتوح Open Pipeline مليونان و122 ألف ريال، ولكن التوقع الموزون 884,400 ريال فقط، أي حوالي 42% من المسار، وهذا الفرق هو ما يجب أن يراه المدير المالي قبل أن يبني ميزانية العام القادم على رقم المسار كاملاً.
- شهر ديسمبر وحده 702 ألف من التوقع، منها 630 ألفاً من صفقة واحدة هي بوابة الطلاب، فإذا تأخرت هذه الصفقة شهراً واحداً تغير شكل الربع كله، وهذا ما يسمى تركز المسار Pipeline Concentration.
- عند الفوز بنظام حجز المواعيد كان تاريخ الإغلاق المتوقع 20 نوفمبر، فظهرت الصفقة الرابحة في نوفمبر حتى عدلنا التاريخ إلى يوم الفوز الفعلي. والقاعدة: عندما تنقل صفقة إلى «فوز» أو «خسارة» فحدث تاريخ الإغلاق إلى اليوم الفعلي، وإلا فإن تقرير الإيرادات Revenue يكذب عليك بهدوء.
- الأوزان 10% و20% و40% و70% افتراضات وضعناها لهذا المثال، والصحيح أن تحسبها من تاريخ صفقاتك: كم صفقة وصلت إلى «عرض» ثم فزت بها فعلاً.
الأوزان من تاريخ صفقاتك بدلاً من التخمين
عندما عرض مدير المبيعات الرقم 884,400 ريال في الاجتماع، سأل المؤسس السؤال الذي يجب أن يسأله كل مدير: من أين جاءت نسبة 70% للتفاوض؟ والجواب الصادق أننا وضعناها لأنها تبدو معقولة، وهذا بالضبط ما كان يحدث في جدول البيانات القديم، فكل شخص يضع النسب التي تبدو له معقولة فيخرج برقم مختلف. والطريقة الأفضل أن تحسب الوزن من صفقاتك المغلقة: من كل الصفقات التي وصلت إلى مرحلة معينة ثم أغلقت، كم منها انتهى بالفوز؟
جمعنا لهذا المثال تاريخاً من 30 صفقة مغلقة في السنة السابقة، وهي بيانات مثال وليست من عميل حقيقي، وكتبنا لكل مجموعة منها آخر مرحلة وصلت إليها قبل الإغلاق والنتيجة. وفي Twenty تستطيع أن تبني هذا الملف من الجدول الزمني لكل صفقة، أو أبسط من ذلك بحقل مخصص اسمه «أعلى مرحلة» يحدثه نفس المستقبل الذي يستقبل الـ Webhook. والملف lab/history.csv:
max_stage,outcome,deals
QUALIFIED,LOST,8
DISCOVERY,LOST,8
PROPOSAL,LOST,6
NEGOTIATION,LOST,2
NEGOTIATION,WON,6ونحفظ الصفقات الثماني كما كانت في نهاية التجربة، بعد التعديلات الثلاثة في القسم السابق، في الملف lab/snapshot.json لكي نعيد الحساب دون أن نشغل Twenty مرة أخرى، وهي نفس بيانات seed.mjs بعد طلبات PATCH:
[
{"name": "نظام حجز مواعيد للعيادات", "sar": 480000, "stage": "WON", "month": "2026-10"},
{"name": "بوابة الطلاب والدفع الإلكتروني", "sar": 900000, "stage": "NEGOTIATION", "month": "2026-12"},
{"name": "ربط المتجر الإلكتروني مع ERP", "sar": 180000, "stage": "PROPOSAL", "month": "2026-12"},
{"name": "تطبيق تتبع الشحنات", "sar": 620000, "stage": "QUALIFIED", "month": "2027-01"},
{"name": "نظام إدارة القضايا", "sar": 95000, "stage": "WON", "month": "2026-10"},
{"name": "لوحة مراقبة خطوط الإنتاج", "sar": 210000, "stage": "LOST", "month": "2026-10"},
{"name": "استضافة وصيانة سنوية", "sar": 72000, "stage": "NEGOTIATION", "month": "2026-11"},
{"name": "مرحلة ثانية: تطبيق المرضى", "sar": 350000, "stage": "DISCOVERY", "month": "2027-02"}
]ثم السكربت lab/weights.py، وهو بلا أي مكتبة خارجية:
# Stage weights from closed deals, then the forecast again with those weights.
# history.csv and snapshot.json are example data (see the article).
import csv, json, math
ORDER = ["QUALIFIED", "DISCOVERY", "PROPOSAL", "NEGOTIATION"]
FIXED = {"QUALIFIED": 0.1, "DISCOVERY": 0.2, "PROPOSAL": 0.4, "NEGOTIATION": 0.7}
def wilson(k, n, z=1.96):
p = k / n
d = 1 + z * z / n
c = (p + z * z / (2 * n)) / d
h = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
return c - h, c + h
reached = {s: 0 for s in ORDER}
won = {s: 0 for s in ORDER}
for row in csv.DictReader(open("history.csv", encoding="utf-8")):
top, n = ORDER.index(row["max_stage"]), int(row["deals"])
for s in ORDER[: top + 1]:
reached[s] += n
if row["outcome"] == "WON":
won[s] += n
print("stage reached won win rate 95% range fixed")
learned = {}
for s in ORDER:
k, n = won[s], reached[s]
lo, hi = wilson(k, n)
learned[s] = k / n
print(f"{s:<12} {n:>7} {k:>4} {k/n:>7.0%} {lo:>4.0%}-{hi:<4.0%} {FIXED[s]:>6.0%}")
deals = json.load(open("snapshot.json", encoding="utf-8"))
def forecast(weights, moves=None):
months = {}
for d in deals:
if d["stage"] in ("WON", "LOST"):
continue
m = (moves or {}).get(d["name"], d["month"])
months[m] = months.get(m, 0) + d["sar"] * weights[d["stage"]]
return months
a, b = forecast(FIXED), forecast(learned)
print("\nmonth fixed weights learned weights")
for m in sorted(set(a) | set(b)):
print(f"{m} {a.get(m,0):>13,.0f} {b.get(m,0):>15,.0f}")
print(f"total {sum(a.values()):>13,.0f} {sum(b.values()):>15,.0f}")
top = max((d for d in deals if d["stage"] not in ("WON", "LOST")), key=lambda d: d["sar"] * learned[d["stage"]])
share = top["sar"] * learned[top["stage"]] / sum(b.values())
print(f"\nlargest deal: {top['name']} = {share:.0%} of the learned forecast")
slip = forecast(learned, {top["name"]: "2027-01"})
print(f"if it slips to 2027-01: 2026-12 falls from {b['2026-12']:,.0f} to {slip['2026-12']:,.0f}")في الكود أعلاه لاحظ التالي:
- الصفقة التي وصلت إلى التفاوض مرت أيضاً بكل المراحل قبلها، لذلك تحسب في كل مرحلة حتى أعلى مرحلة وصلت إليها، وهذا ما تفعله الحلقة على
ORDER[: top + 1]. - الدالة
wilsonتحسب مدى فاصل الثقة Confidence Interval بطريقة Wilson عند 95%، وهي مناسبة للأعداد الصغيرة أكثر من الطريقة المعتادة التي قد تعطي نسبة أقل من صفر أو أكبر من 100%. - الدالة
forecastتأخذ الأوزان، وتأخذ اختيارياً تاريخاً جديداً لصفقة معينة، لكي نرى ماذا يحدث للشهر إذا تأخرت.
ونشغله:
docker run --rm -v "$(pwd)/lab:/w" -w /w python:3.13.17-slim python weights.pyوالمخرج سوف يكون كما يلي:
stage reached won win rate 95% range fixed
QUALIFIED 30 6 20% 10%-37% 10%
DISCOVERY 22 6 27% 13%-48% 20%
PROPOSAL 14 6 43% 21%-67% 40%
NEGOTIATION 8 6 75% 41%-93% 70%
month fixed weights learned weights
2026-11 50,400 54,000
2026-12 702,000 752,143
2027-01 62,000 124,000
2027-02 70,000 95,455
total 884,400 1,025,597
largest deal: بوابة الطلاب والدفع الإلكتروني = 66% of the learned forecast
if it slips to 2027-01: 2026-12 falls from 752,143 to 77,143في المخرج أعلاه لاحظ التالي، سطراً سطراً:
- الجدول الأول: كل الصفقات الثلاثين بدأت عميلاً مؤهلاً، وفزنا بست منها، أي 20%، وهذا ضعف الوزن الذي خمناه. ومن 8 صفقات وصلت إلى التفاوض فزنا بست، أي 75%، قريب من 70% التي وضعناها. فالتخمين كان متشائماً في أول المسار وقريباً في آخره، وهذا شائع لأن الفريق يتذكر الصفقات الكبيرة التي خسرها في البداية أكثر مما يتذكر الصغيرة التي فاز بها.
- عمود المدى: نسبة التفاوض 75% مبنية على 8 صفقات فقط، والمدى المحتمل لها من 41% إلى 93%. أي أن البيانات لا تقول إن الوزن الصحيح 75%، وإنما تقول إنه في مكان ما بين النصف تقريباً وكل الصفقات. وهذا هو الشيء الذي لا يظهر أبداً في جدول البيانات، ويجب أن يعرفه المدير المالي قبل أن يعتمد على الرقم.
- الجدول الثاني: بالأوزان الجديدة ارتفع التوقع من 884,400 إلى 1,025,597 ريال، وأكبر فرق في يناير، لأن تطبيق تتبع الشحنات ما زال عميلاً مؤهلاً، ووزنه ارتفع من 10% إلى 20% فتضاعف أثره من 62 ألفاً إلى 124 ألفاً.
- سطر الصفقة الأكبر: بوابة الطلاب وحدها 66% من التوقع كله، أي ثلثاه.
- السطر الأخير: إذا تأخر توقيع البوابة إلى يناير، وهذا يحدث كثيراً مع الجامعات لأن العقد يمر على أكثر من لجنة، فإن توقع ديسمبر ينزل من 752 ألفاً إلى 77 ألفاً، أي يختفي 90% منه بتأخير صفقة واحدة شهراً واحداً.

فماذا قدم الفريق للمؤسس في النهاية؟ ليس رقماً واحداً، وإنما ثلاثة: التوقع بالأوزان من التاريخ 1,025,597 ريال، والصفقة التي يعتمد عليها ثلثا الرقم، وما يحدث للشهر إذا تأخرت. وهذا أنفع من رقم دقيق المظهر، لأنه يقول للمؤسس أين يضع وقته هذا الشهر: في اجتماع مع لجنة الجامعة، وليس في مراجعة جدول البيانات. ولاحظ أيضاً أن هذه الطريقة تحتاج أن يكون تاريخ الصفقات في النظام صادقاً، أي أن تنقل الصفقة الخاسرة إلى «خسارة» فعلاً بدلاً من أن تبقى في التفاوض شهوراً، وإلا فإن نسبة الفوز من التفاوض تبدو أعلى مما هي في الحقيقة. وقد شرحنا الفرق بين التوقع الموزون والتوقع بالفئات Forecast Categories في مقال مسار البيع.
إرسال التغييرات إلى نظام آخر عبر Webhook
عندما يفوز فريق المبيعات بصفقة يحتاج قسم المالية أن يعرف لكي يصدر الفاتورة، والحل البسيط أن يرسل البائع بريداً، وهذا يتأخر وينسى. الحل الأفضل أن يرسل Twenty طلباً إلى نظام الفوترة كلما تغيرت صفقة، وهذا هو الـ Webhook كما في توثيق الـ Webhooks. نبدأ بالمستقبل hook.js، وهو يتحقق من التوقيع قبل أن يثق بأي شيء في الطلب:
// Minimal webhook receiver: verifies the Twenty signature and logs one line per event.
const http = require('node:http');
const crypto = require('node:crypto');
const SECRET = process.env.WEBHOOK_SECRET || '';
http.createServer((req, res) => {
let body = '';
req.on('data', (c) => (body += c));
req.on('end', () => {
const ts = req.headers['x-twenty-webhook-timestamp'] || '';
const sig = req.headers['x-twenty-webhook-signature'] || '';
const expected = crypto.createHmac('sha256', SECRET).update(`${ts}:${body}`).digest('hex');
const valid = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
let e = {};
try { e = JSON.parse(body); } catch {}
const r = e.record || e.data || {};
console.log(JSON.stringify({ valid, event: e.eventName, name: r.name, stage: r.stage,
amountSAR: r.amount && r.amount.amountMicros / 1e6, updatedFields: e.updatedFields }));
res.writeHead(valid ? 200 : 401).end();
});
}).listen(8080, () => console.log('listening on 8080'));ولاحظ أن التوقيع يحسب على النص الخام للطلب كما وصل، وليس على كائن JSON بعد تحويله ثم إعادته نصاً كما في مثال التوثيق، والسبب أن أي اختلاف في المسافات أو ترتيب الحقول يغير الهاش فيفشل التحقق.
بعد ذلك ننشئ الـ Webhook من Settings ثم Developers ثم Webhooks، ونضع العنوان والوصف والسر نفسه الموجود في WEBHOOK_SECRET، ونختار من الفلاتر الفرص فقط لكي لا يصل إلى نظام الفوترة كل تعديل في جهات الاتصال:

وهنا واجهتنا مشكلتان قبل أن يصل أول طلب، وكلتاهما ستقابلك إذا كان نظام الفوترة على نفس الشبكة الداخلية:
- زر الحفظ معطل: كتبنا أولاً العنوان
http://mkg-hook:8080/twentyباسم الخدمة في Docker، فبقي زر الحفظ رمادياً دون أي رسالة، والسبب أن النموذج لا يقبل عنواناً لا يحتوي اسم نطاق فيه نقطة. لذلك أعطينا الخدمة الاسم الإضافيhook.example.comداخل شبكة Docker، فقبل النموذج العنوان. - الطلب لا يصل: بعد الحفظ غيرنا مرحلة صفقة، فظهر في سجل الـ worker سطر
Outbound HTTP request: POST http://hook.example.com:8080/twentyوأن المهمة انتهت خلال خمسة أجزاء من الثانية، ولكن سجل المستقبل بقي فارغاً، ولا توجد أي رسالة خطأ أو تحذير. والسبب حماية SSRF في Twenty، فهو يرفض أي اتصال صادر إلى عنوان IP خاص، كما في قسم Outbound Connections to Internal Hosts من صفحة الإعداد، ونظام الفوترة داخل شبكة Docker عنوانه خاص بطبيعة الحال. والحل أن تضيف اسم المضيف بالضبط إلى المتغيرOUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTSكما في ملف Compose أعلاه، ولا تضع فيه*لأن ذلك يلغي الحماية لكل الأنظمة الداخلية.
وبعد إعادة تشغيل الـ server والـ worker بالمتغير الجديد، غيرنا مرحلة صفقة ربط المتجر وقيمتها، فكان سجل المستقبل كما يلي:
docker compose logs hooklistening on 8080
{"valid":true,"event":"opportunity.updated","name":"ربط المتجر الإلكتروني مع ERP","stage":"PROPOSAL","amountSAR":180000,"updatedFields":["amount","stage"]}ووصلت أيضاً الأحداث التي وقعت أثناء توقف الـ worker بعد عودته، لأنها كانت محفوظة في طابور Redis. وفي المخرج أعلاه لاحظ التالي:
- شكل الطلب الفعلي في الإصدار v2.51.0 يختلف عن المثال في التوثيق، فالحدث في الحقل
eventNameوليسevent، والسجل فيrecordوليسdata، ومعهماupdatedFieldsوobjectMetadataوworkspaceIdوwebhookIdوeventDate. لذلك اكتب المستقبل على طلب حقيقي التقطته، لا على مثال التوثيق. - الحقل
updatedFieldsيذكر ما تغير فقط، فيستطيع نظام الفوترة أن يتجاهل كل تحديث لا يغيرstageإلىWON. - الطلب يحمل السجل كاملاً بما فيه المبلغ والمرحلة، فإذا كان المستقبل خارج شبكتك فأنت ترسل بيانات العملاء إلى طرف آخر، وهذا يدخل في مسؤولياتك بحسب نظام حماية البيانات الشخصية.
والآن ماذا يحدث إذا أرسل أحد طلباً مزوراً إلى المستقبل يدعي أن صفقة فازت؟ جربنا ذلك من داخل الـ Container بتوقيع خاطئ:
docker compose exec hook curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8080/twenty \
-H 'X-Twenty-Webhook-Timestamp: 1793000000000' -H 'X-Twenty-Webhook-Signature: 00ff' \
-d '{"eventName":"opportunity.updated","record":{"name":"صفقة مزورة","stage":"WON"}}'401
{"valid":false,"event":"opportunity.updated","name":"صفقة مزورة","stage":"WON"}رفض المستقبل الطلب، وهذا هو سبب السر: بدونه يستطيع أي شخص يعرف عنوان نظام الفوترة أن يصدر فاتورة لصفقة لم تحدث. وإذا أردت أن تبني منطقاً أكبر، مثل إنشاء الفاتورة في نظام ERP عند الفوز، فاجعل المستقبل سير عمل في n8n كما في مقال سير العمل في n8n، وقد شرحنا ربط منصة SaaS بأنظمة العميل بشكل أوسع في مقال التكامل مع أنظمة العميل.
التوقيع وحده لا يمنع الفاتورة المكررة
بعد أسبوع من تشغيل الـ Webhook سألت المحاسبة سؤالاً مهماً: إذا وصلنا نفس إشعار الفوز مرتين، هل نصدر فاتورتين؟ والمستقبل hook.js يتحقق من أن الطلب جاء من Twenty، ولكنه لا يتحقق من أنه جاء الآن، ولا من أنه لم يصل قبل ذلك. فإذا التقط شخص طلباً حقيقياً من سجل Reverse Proxy أو من أداة مراقبة، يستطيع أن يرسله مرة أخرى بنفس التوقيع، فيمر التحقق لأن النص والتوقيع لم يتغيرا. وهذا ما يسمى هجوم إعادة الإرسال Replay Attack.
وللتحقق من هذا السلوك بمعزل عن بقية النظام كتبنا سكربتاً يرسل طلبات موقعة بنفس طريقة Twenty التي تحقق منها hook.js مع الطلبات الحقيقية في القسم السابق: HMAC SHA256 على النص <timestamp>:<body>. والحدث فيه مثال بنفس شكل الطلب الحقيقي، والسكربت lab/replay.py:
# Sends signed test events to a webhook receiver the way Twenty signs them:
# HMAC-SHA256 over "<timestamp>:<raw body>". Example data, not a real deal.
import hashlib, hmac, json, os, sys, time, urllib.request
URL, SECRET = sys.argv[1], os.environ["WEBHOOK_SECRET"].encode()
def send(label, body, ts, sig=None):
sig = sig or hmac.new(SECRET, f"{ts}:{body}".encode(), hashlib.sha256).hexdigest()
req = urllib.request.Request(URL, data=body.encode(), method="POST", headers={
"Content-Type": "application/json",
"X-Twenty-Webhook-Timestamp": str(ts), "X-Twenty-Webhook-Signature": sig})
try:
code = urllib.request.urlopen(req).status
except urllib.error.HTTPError as e:
code = e.code
print(f"{label:<34} {code}")
return sig
event = {"eventName": "opportunity.updated",
"record": {"name": "نظام حجز مواعيد للعيادات", "stage": "WON",
"amount": {"amountMicros": 480000000000, "currencyCode": "SAR"}},
"updatedFields": ["stage"]}
raw = json.dumps(event, ensure_ascii=False, separators=(",", ":"))
now = int(time.time() * 1000)
sig = send("1 original event", raw, now)
send("2 same request again (replay)", raw, now, sig)
send("3 valid signature, 1 hour old", raw, now - 3600_000)
pretty = json.dumps(event) # what a proxy or framework may re-serialise to
send("4 body re-serialised, same sig", pretty, now, sig)
print(f"raw body {len(raw.encode())} bytes, re-serialised {len(pretty.encode())} bytes")السكربت يرسل أربعة طلبات: الحدث الأصلي، ثم نفس الطلب كما هو، ثم نفس الحدث بتوقيع صحيح ولكن بوقت قبل ساعة، ثم نفس الحدث بعد إعادة كتابة JSON بالطريقة الافتراضية في Python مع التوقيع الأصلي، وهذا ما يحدث عندما يقرأ إطار عمل أو Proxy الطلب ثم يعيد كتابته قبل أن يصل إلى الكود. ونشغل المستقبل في Container والسكربت في Container آخر على نفس الشبكة، مع سر عشوائي في متغير بيئة فقط:
export WEBHOOK_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(24))")
docker network create mkg-lab
docker run -d --rm --name mkg-hook --network mkg-lab -e WEBHOOK_SECRET \
-v "$(pwd)/lab:/w:ro" -w /w node:24.22.1-bookworm node hook.js
docker run --rm --network mkg-lab -e WEBHOOK_SECRET -v "$(pwd)/lab:/w:ro" -w /w \
python:3.13.17-slim python -I replay.py http://mkg-hook:8080/twenty
docker logs mkg-hookوالمخرج كان كما يلي:
1 original event 200
2 same request again (replay) 200
3 valid signature, 1 hour old 200
4 body re-serialised, same sig 401
raw body 201 bytes, re-serialised 298 bytesوفي سجل المستقبل أربعة أسطر، الثلاثة الأولى منها "valid":true لنفس الصفقة "stage":"WON" بمبلغ 480 ألف ريال. في المخرج أعلاه لاحظ التالي:
- السطران 2 و3: قبل المستقبل نفس الحدث ثلاث مرات، ولو كان يصدر فاتورة عند كل فوز لأصدر ثلاث فواتير لعقد واحد. والطلب الثالث أخطر، لأنه يعني أن أي طلب قديم موقع يبقى صالحاً إلى الأبد.
- السطر 4: رفض المستقبل نفس الحدث بعد إعادة كتابته، مع أن البيانات هي نفسها، لأن النص تغير من 201 بايت إلى 298 بايت: Python كتبت الحروف العربية بالصيغة
نوأضافت مسافات بعد الفواصل. وهذا يثبت عملياً ما قلناه عن حساب التوقيع على النص الخام: إذا كان مستقبلك خلف شيء يعيد كتابة الطلب، فسوف ترفض كل الطلبات الصحيحة.
والإصلاح في الملف lab/hook2.js: نرفض الطلب الذي يبعد وقته عن وقت المستقبل أكثر من خمس دقائق، ونتذكر التوقيعات التي قبلناها خلال هذه الدقائق الخمس ونرفض تكرارها:
// hook.js plus two checks: reject old timestamps and reject a signature seen before.
const http = require('node:http');
const crypto = require('node:crypto');
const SECRET = process.env.WEBHOOK_SECRET || '';
const MAX_AGE_MS = 5 * 60 * 1000;
const seen = new Map(); // signature -> time first seen
http.createServer((req, res) => {
let body = '';
req.on('data', (c) => (body += c));
req.on('end', () => {
const ts = req.headers['x-twenty-webhook-timestamp'] || '';
const sig = req.headers['x-twenty-webhook-signature'] || '';
const expected = crypto.createHmac('sha256', SECRET).update(`${ts}:${body}`).digest('hex');
const valid = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
const now = Date.now();
for (const [s, t] of seen) if (now - t > MAX_AGE_MS) seen.delete(s);
let code = 200, why = 'ok';
if (!valid) { code = 401; why = 'bad signature'; }
else if (Math.abs(now - Number(ts)) > MAX_AGE_MS) { code = 401; why = 'too old'; }
else if (seen.has(sig)) { code = 409; why = 'replay'; }
else seen.set(sig, now);
console.log(JSON.stringify({ code, why }));
res.writeHead(code).end();
});
}).listen(8080, () => console.log('listening on 8080'));وشغلنا نفس السكربت على المستقبل الجديد باسم mkg-hook2، فكان المخرج كما يلي:
1 original event 200
2 same request again (replay) 409
3 valid signature, 1 hour old 401
4 body re-serialised, same sig 401
raw body 201 bytes, re-serialised 298 bytesوسجل المستقبل يذكر السبب في كل سطر: ok ثم replay ثم too old ثم bad signature.

وفي هذا الإصلاح ثلاثة أمور يجب أن تعرفها قبل أن تنقله إلى نظام حقيقي:
- الساعة: فحص الوقت يفترض أن ساعة سيرفر Twenty وساعة المستقبل متقاربتان، فإذا كان أحدهما متأخراً عشر دقائق فسوف ترفض كل الطلبات. لذلك فعل مزامنة الوقت NTP على السيرفرين، ولا تجعل المدة أقصر من دقائق قليلة.
- الذاكرة: قائمة التوقيعات في ذاكرة العملية، فتضيع عند إعادة التشغيل، ولا تشترك فيها نسختان من المستقبل. وفي نظام حقيقي ضعها في Redis مع مدة انتهاء TTL بنفس الدقائق الخمس.
- الفاتورة نفسها: فحص التكرار في المستقبل يمنع الطلب المكرر، ولكنه لا يمنع حدثين مختلفين لنفس الفوز، مثل أن ينقل البائع الصفقة إلى «فوز» ثم إلى «تفاوض» بالخطأ ثم إلى «فوز» مرة أخرى، فيصل حدثان صحيحان بتوقيعين مختلفين. والحل في نظام الفوترة: أن يكون مفتاح الفاتورة هو معرف الصفقة، فلا ينشئ فاتورة ثانية لصفقة لها فاتورة، وهذا هو مبدأ Idempotency.
ولاحظ أن الرد 409 للطلب المكرر مقصود: المستقبل يقول إنه استلم هذا الطلب من قبل، ولا يقول إن الطلب فاسد، فإذا أعاد المرسل الإرسال لأن الرد الأول ضاع في الشبكة، فالحدث قد عولج فعلاً ولا تحتاج شيئاً آخر.
الوصول من خارج السيرفر
صفحة تأمين النظام في التوثيق الرسمي توصي بأن يبقى Twenty خاصاً بالفريق، والسبب أن الواجهة نفسها تعمل على المسارات /graphql و/rest، فنشرها للإنترنت ينشر كل شيء. لذلك الأنسب لفريق صغير أن يصل إليه عبر شبكة خاصة مثل WireGuard. وإذا احتجت نطاقاً بشهادة TLS داخل هذه الشبكة، فهذا مثال لملف Caddyfile على طريقة دليل Caddy:
crm.example.com {
reverse_proxy 127.0.0.1:3000
}وعند تغيير النطاق غير SERVER_URL في ملف .env إلى https://crm.example.com ثم أعد تشغيل الـ server والـ worker، لأن الروابط في الرسائل والدعوات تبنى منه. ولم نجرب إصدار الشهادة في هذا المختبر لأنه يحتاج نطاقاً حقيقياً.
التحقق من النجاح
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/healthzيرجع200.docker compose psيعرض server بحالةhealthyوالـ worker يعمل.- الأمر التالي يعرض حالة الترحيل لكل مساحة عمل، ويجب أن يكون
Up to date:
docker compose exec server yarn command:prod upgrade:statusWorkspace
Inferred version: 2.51.0
Status: Up to date
Executed by: v2.51.0
Summary
Instance: Up to date
Workspaces: 1 up to date, 0 behind, 0 failed (1 total)- تغيير مرحلة صفقة يظهر سطراً في سجل المستقبل خلال ثوان، فإذا لم يظهر فراجع المشكلات الشائعة.
النسخ الاحتياطي Backup والاستعادة Restore
البيانات في مكانين: قاعدة PostgreSQL وفيها كل السجلات، والـ Volume المسمى server-data وفيه الملفات المرفوعة والمرفقات، وكان حجمه 28.5 ميجابايت في تجربتنا. ومعهما ملف .env لأنه يحتوي ENCRYPTION_KEY. نأخذ نسخة من قاعدة البيانات بصيغة pg_dump المضغوطة:
docker compose exec db pg_dump -U twenty -d twenty -Fc -f /tmp/twenty.dump
docker compose cp db:/tmp/twenty.dump ./twenty-$(date +%F).dumpواستغرق ذلك ثانية ونصفاً، وحجم الملف 1.36 ميجابايت لمساحة عمل فيها بياناتنا التجريبية. والنسخة التي لم تجرب استعادتها لا تعد نسخة، لذلك استعدناها في قاعدة جديدة على نفس السيرفر وعددنا الصفقات:
docker compose exec db createdb -U twenty twenty_restore
docker compose exec db pg_restore -U twenty -d twenty_restore /tmp/twenty.dump
docker compose exec db psql -U twenty -d twenty_restore -At \
-c "select schema_name from information_schema.schemata where schema_name like 'workspace_%'"البيانات في Twenty محفوظة في مخطط Schema مستقل لكل مساحة عمل اسمه يبدأ بـ workspace_، فنستخدم الاسم الذي يرجعه الأمر أعلاه:
docker compose exec db psql -U twenty -d twenty_restore -At \
-c "select count(*), sum(\"amountAmountMicros\")/1000000 from workspace_xxxx.opportunity where \"deletedAt\" is null"8|2907000.000000000000ثمانية فرص بمجموع مليونين و907 آلاف ريال، وهو مجموع المسار المفتوح والرابح والخاسر في التوقع أعلاه، واستغرقت الاستعادة عشر ثوان تقريباً. وقد شرحنا قاعدة 3-2-1 لحفظ النسخ خارج السيرفر في دليل النسخ الاحتياطي.
التحديث Upgrade إلى إصدار أحدث
Twenty يصدر إصدارات بسرعة كبيرة، ففي الأسبوع الذي جربنا فيه صدرت v2.48.1 وv2.49.0 وv2.50.0 وv2.50.1 وv2.51.0 كما في صفحة Docker Hub، والإصدار v2.51.0 صدر في 23 أكتوبر 2026. ودليل التحديث الرسمي يقول إن الترحيل يعمل تلقائياً عند التشغيل، وإن الترقية عبر عدة إصدارات مدعومة منذ v1.23، وإن v2.34 وما بعده يحتاج PostgreSQL 15 أو أحدث. والخطوات:
- خذ نسخة قاعدة البيانات كما في القسم السابق.
- غير الوسم في سطري
serverوworkerإلى الإصدار الجديد. - شغل
docker compose up -dوانتظر رسالةsuccessfully started، وقد يطول الترحيل الأول. - تحقق بالأمر
upgrade:status، ثم افتح لوحة Kanban وتأكد أن الأعمدة والمراحل كما هي.
مشكلات شائعة وحلولها
dependency failed to start: container ... is unhealthy: الـ server لم ينته من الترحيل خلال مهلة فحص الصحة، فأضفstart_periodكما في الملف أعلاه، وتابع السجل حتى تظهرsuccessfully started.- رسالة
column KeyValuePairEntity.applicationId does not existفي أول التشغيل: ظهرت لنا قبل انتهاء الترحيل ثم اختفت، فهي من محاولة قراءة الإعدادات قبل إنشاء الجداول، ولا تحتاج تدخلاً إلا إذا بقيت بعد اكتمال الترحيل. - لوحة Kanban فارغة والعداد فيه سجلات: غيرت قيم حقل المرحلة من الـ API فحذفت مجموعات العرض، فأنشئها كما في قسم المراحل.
- زر حفظ الـ Webhook معطل: العنوان بلا نقطة في اسم المضيف، فاستخدم اسماً كاملاً.
- الـ Webhook لا يصل ولا يوجد خطأ: المستقبل على عنوان خاص، فأضف اسمه إلى
OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTSعلى الـ server والـ worker معاً، وتأكد أن الـ worker يعمل لأنه هو من يرسل. Missing authentication token: الطلب بدون الترويسةAuthorization: Bearer، أو المتغير فارغ في الجلسة الحالية.- أرقام غريبة في المبالغ: نسيت أن المبلغ بالجزء من المليون، فاضرب في مليون عند الكتابة واقسم عند القراءة.
إزالة التجربة
إذا جربت على جهازك وتريد إزالة كل شيء بما فيه قاعدة البيانات:
cd /opt/crm
docker compose down -v
docker rmi twentycrm/twenty:v2.51.0ماذا يحدث عندما يتغير شيء؟
بعد شهرين من استخدام النظام مر الفريق بمواقف لم تكن في خطة التثبيت، وهذه أهمها وما يحدث في كل منها:
- توقف الـ worker يوماً كاملاً دون أن يلاحظ أحد: الواجهة تعمل كالمعتاد لأن الـ server هو من يخدمها، ولكن الـ Webhooks لا تخرج. وقد رأينا في قسم الـ Webhook أن الأحداث محفوظة في طابور Redis وتصل بعد عودة الـ worker، فلا يضيع شيء ما دام Redis لم يفقد بياناته، وهذا سبب سياسة
noeviction. ولكن المحاسبة تعرف بالفوز متأخرة، لذلك أضف فحصاً يتأكد أن الـ Container الخاص بالـ worker يعمل، وليس فقط الـ server. - ضاع ملف
.envوبقيت نسخة قاعدة البيانات: السجلات تعود كما هي، ولكن الأسرار المشفرة بالمفتاحENCRYPTION_KEY، مثل توكنات الحسابات المرتبطة، لا يمكن فك تشفيرها، فتحتاج أن تربط هذه الحسابات من جديد. لذلك احفظ الملف في مدير أسرار منفصل عن النسخة الاحتياطية، ولا تضعه معها في نفس المكان. - ترك أحد البائعين الشركة: عطل حسابه من الإعدادات، وانقل صفقاته المفتوحة إلى زميل، وراجع مفاتيح الـ API التي أنشأها، لأن المفتاح ليس مرتبطاً بجلسة المستخدم في المتصفح، فاحذفه أو غير دوره صراحة.
- طلب عميل حكومي أن تبقى بياناته داخل المملكة: النظام على سيرفرك، فأنت من يختار مكانه، ولكن انتبه لما يخرج منه: الـ Webhook يرسل السجل كاملاً، فإذا كان المستقبل خدمة خارج المملكة فقد نقلت بيانات العميل إلى الخارج. وقد شرحنا ما يلزمك في مقال حماية البيانات الشخصية للخدمات المستضافة.
- صدر إصدار جديد فيه ميزة يريدها الفريق: لا تحدث في بداية يوم العمل، فالترحيل الأول أخذ عشر دقائق في تجربتنا، والنظام لا يعمل خلالها. خذ النسخة واختر وقتاً هادئاً، واتبع قسم التحديث.
- تضاعف عدد الصفقات: التوقع من
forecast.mjsيطلب 200 سجل فقط بالمتغيرlimit، فإذا تجاوزت الصفقات هذا العدد فالتوقع ناقص دون أي رسالة خطأ. لذلك أضف التصفح Pagination في السكربت قبل أن تحتاجه، وأعد حساب الأوزان كل ربع سنة لأن التاريخ الجديد يغيرها.
قائمة تحقق قبل أن يعتمد الفريق على النظام
| البند | كيف تتحقق منه |
|---|---|
الإصدار مثبت في ملف Compose وليس latest | سطر image للـ server والـ worker |
| الـ server والـ worker يعملان معاً | docker compose ps |
| مراحل البيع لها شرط خروج مكتوب يعرفه الفريق | صفحة داخلية أو وصف الحقل |
| أعمدة Kanban موجودة لكل مرحلة | فتح لوحة الفرص بعد أي تغيير في المراحل |
| البيانات التجريبية محذوفة | لا توجد شركات أو فرص لم ينشئها الفريق |
| مفاتيح الـ API بأقل دور يكفي | Settings ثم Roles |
| الأوزان محسوبة من صفقات مغلقة، ومعها المدى | مخرج weights.py |
| المستقبل يرفض التوقيع الخاطئ والطلب القديم والمكرر | مخرج replay.py |
| الفاتورة لا تتكرر لنفس الصفقة | مفتاح فريد على معرف الصفقة في نظام الفوترة |
| النسخة الاحتياطية مجربة بالاستعادة | عدد الفرص في القاعدة المستعادة |
ملف .env محفوظ منفصلاً عن النسخة | مدير الأسرار |
| النظام غير منشور للإنترنت | المنفذ على 127.0.0.1 والوصول عبر شبكة خاصة |
الخلاصة
وصلنا لنهاية الموضوع، وأهم ما فيه:
- Twenty يعمل بأربع Containers ويحتاج حوالي 1.8 جيجابايت من الذاكرة، والتشغيل الأول قد يأخذ دقائق طويلة، فأعطه
start_periodكافياً وثبت الإصدار. - الواجهة العربية تعمل من اليمين إلى اليسار، مع ترجمات تحتاج مراجعة وتسميات مختلطة تقص في الأعمدة الضيقة.
- تغيير مراحل البيع من الـ API يحذف أعمدة لوحة Kanban، فأعد إنشاءها بـ
createManyViewGroups. - الاستيراد من CSV يدعم العربية، وما لا يجد حقلاً مقابلاً تنشئ له حقلاً مخصصاً قبل الاستيراد.
- التوقع الموزون من الـ API أعطى 884,400 ريال من مسار مفتوح قيمته 2,122,000 ريال، وأغلبه في صفقة واحدة.
- الأوزان من تاريخ 30 صفقة مغلقة رفعت التوقع إلى 1,025,597 ريال، ولكن ثلثيه من صفقة واحدة، وتأخرها شهراً ينزل ديسمبر من 752 ألفاً إلى 77 ألفاً.
- المستقبل الذي يتحقق من التوقيع فقط قبل نفس الطلب ثلاث مرات، فأضف فحص الوقت والتكرار، واجعل الفاتورة نفسها لا تتكرر لنفس الصفقة.
- الـ Webhook موقع بـ HMAC، ولا يصل إلى عنوان خاص إلا إذا أضفته إلى
OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS، وشكل الطلب الفعلي يختلف عن مثال التوثيق.
تدريب عملي
- أضف حقلاً مخصصاً اسمه «سبب الخسارة» من نوع SELECT إلى الفرص، واجعل المستقبل يرفض أي حدث ينقل صفقة إلى
LOSTدون أن يكون الحقل معبأً. - عدل
forecast.mjsلكي يقرأ الأوزان من مخرجweights.pyبدلاً من الأرقام الثابتة، واحسب التاريخ من صفقاتك المغلقة في Twenty نفسه. - انقل ذاكرة التكرار في
hook2.jsمن الذاكرة إلى Redis، وشغل نسختين من المستقبل، ثم أعد تشغيلreplay.pyوتأكد أن الطلب المكرر يرفض في النسختين.
وأقرب المقالات إلى هذا الدليل على الموقع:
دليلإدارة علاقات العملاء CRM: Salesforce وبدائله مفتوحة المصدركيف تختار نظام CRM لفريق مبيعاتك: أربعة أسئلة، ومقارنة العربية والأسعار، وتكلفة فريق من خمسة في السنة.
دليلمسار البيع Sales Pipeline: المراحل والتوقعات Forecastكيف تقسم صفقاتك إلى مراحل واضحة وتحسب توقع الإيرادات بالآلة الحاسبة، مع مثال محسوب خطوة بخطوة.
دليلما هو ERP وCRM؟ ومتى تحتاج شركتك إليهماما الذي تفعله أنظمة ERP وCRM، ومتى تحتاجها شركتك فعلاً، ولماذا يتعثر تطبيقها، وما علاقتها بالفاتورة الإلكترونية في المملكة.
دليلOdoo Community: نظام ERP لشركتك على سيرفرككيف تثبت Odoo Community على سيرفرك، وتمر بدورة بيع كاملة حتى الدفع، وترسل فاتورة إلى بيئة الاختبار في منصة فاتورة.سجل التحديثات
- أكتوبر 2026: إضافة قصة الفريق، ومختبر أوزان المراحل من تاريخ الصفقات
lab/weights.pyعلى Python 3.13.17، ومختبر الطلبات المكررة والقديمة على المستقبلlab/replay.pyوlab/hook2.jsعلى node:24.22.1-bookworm، وماذا يحدث عندما يتغير شيء، وقائمة تحقق، وشكلين جديدين. والأرقام والصور الخاصة بـ Twenty من تجربتنا على الإصدار v2.51.0. - أكتوبر 2026: كتابة الدليل واختباره على Twenty v2.51.0 مع postgres:16.15 وredis:7.2.16 وnode:24.22.1-bookworm للمستقبل، على Docker Engine 29.8.0.