إجراءات التغيير

تعريف إجراء تغيير#

استخدم إجراء التغيير لتحديث سجل في نظامك الخاص، مثل إلغاء طلب. افتح الوكيل ← الإجراءات، واضبط السر الخاص بالوكيل في العملاء المسجّلون للدخول، ثم أضف إجراء تغيير: اسمًا فريدًا، ووصفًا لوقت استخدامه، ونقطة نهاية HTTPS عامة، ومدخلات نصية معرَّفة. الاسم مثل cancel_order يصبح أداة النموذج change_cancel_order. تُحفظ التعديلات على الإجراءات الحالية تلقائيًا؛ انتظر ظهور مؤشر الحفظ.

أبقِ خيار يتطلب عميلًا مسجّلًا للدخول مفعّلًا للسجلات الخاصة. يجب أن تتحقق نقطة النهاية لديك مع ذلك من أن السجل المطلوب يعود إلى معرّف العميل الذي جرى التحقق منه. الاسم أو البريد الإلكتروني أو رقم الطلب المكتوب في المحادثة ليس دليلًا على الهوية. إذا عطّلت هذا الإعداد فقد تكون قيمة customer فارغة (null): اسمح فقط بالتغييرات المناسبة للزوار المجهولين. المدفوعات خارج نطاق هذه الميزة.

اختيار موافقة المالك#

تأكيد العميل مطلوب في كل الأوضاع:

راجع الطلبات المنتظرة في الوكيل ← الإجراءات ← الموافقات. يمكن لمالك الموقع الموافقة أو الرفض. إذا كانت تنبيهات المالك الخاصة عبر Telegram مرتبطة، فسيتضمن التنبيه أيضًا زرَّي موافقة / رفض. لا يمكن استخدامهما إلا من المحادثة الخاصة للمالك المرتبط؛ ولا يمكن للنقرات المنتهية أو المكررة أن تنفّذ الإجراء مرة أخرى. تنتهي صلاحية الموافقة بعد 24 ساعة من تأكيد العميل. يتلقى العميل النتيجة، بما في ذلك الرفض أو انتهاء الصلاحية. تعرض عمليات التشغيل الأخيرة الحالة والطوابع الزمنية والمرجع ومعرّف العميل.

ما تستقبله نقطة النهاية لديك#

لا يُرسل أي طلب عندما يقترح النموذج التغيير. بعد تأكيد العميل وأي موافقة مطلوبة من المالك، يرسل Make Agent Fast ما يلي:

POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b

{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

لا تتضمن قيمة action البادئة change_. يبقى المعرّفان ورأس مفتاح منع التكرار (idempotency) كما هي عند إعادة المحاولة. يحتوي input على سلاسل نصية معرَّفة ومقتطعة المسافات فقط؛ وcustomer إما null أو الكائن الذي جرى التحقق منه ويتضمن id وemail/name الاختياريين.

استخدم أداة التحقق من توقيع عمليات البحث: HMAC-SHA256 باستخدام سر الوكيل على "maf-webhook-v1:" + timestamp + "." + rawBody، بحروف سداسية عشرية صغيرة تسبقها v1=. تحقق من البايتات الأصلية، وحداثة الطابع الزمني، والموقع/الإجراء المتوقعين، وملكية العميل قبل أي كتابة. أزل التكرار لقيمة x-maf-idempotency-key بشكل ذري مع تغييرك واحتفظ بالنتيجة. يجب أن يعيد الطلب المكرر النتيجة المحفوظة دون تغيير السجل مرة أخرى. لا يمكن للقفل على مستوى المنصة أن يحل محل إزالة التكرار في نظامك.

إرجاع النتيجة#

أرجع JSON بحالة 2xx يتضمن الحقل المطلوب status (done أو pending أو failed) والحقول الاختيارية message وreference وcard:

{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}

تتطلب بطاقة الحالة الاختيارية الحقلين title وfields؛ أما kind: "status" فاختياري. وتدعم status: { label, tone } وreference وasOf وlink: { label, url }، كما في عمليات البحث. النبرات هي neutral أو success أو warning أو danger؛ ويجب أن تكون الروابط عناوين HTTPS آمنة. تُرفض حقول المخطط غير المعروفة. اجعل النص قصيرًا وبسيطًا. الحقل الخارجي status هو الذي يحدد النتيجة؛ ولا يمكن لصياغة البطاقة أن تحوّل نتيجة معلّقة إلى نجاح.

استخدم done فقط بعد اكتمال التغيير، وpending عندما لا تزال المعالجة جارية، وfailed عند حدوث فشل معروف. تُعامل مهلات الانتظار وأخطاء الشبكة واستجابات 5xx والاستجابات غير الصالحة على أنها نتيجة غير مؤكدة (unknown). تعيد المطابقة المحاولة بعد دقيقة واحدة ثم بعد خمس دقائق، بحد أقصى ثلاث محاولات تنفيذ وبالمفتاح نفسه؛ وقد تؤخر جدولة قوائم الانتظار هذه الأوقات. تفشل استجابة HTTP 4xx دون إعادة محاولة. عند استنفاد حالات عدم اليقين يفشل التشغيل ويُبلَّغ المالك، لكن هذا لا يثبت أن نظامك لم يُجرِ أي تغيير. حقّق في الأمر قبل بدء تشغيل آخر. لا يؤدي pending إلى تنفيذ آخر.

إرسال استدعاء نهائي موقَّع#

عند حسم تشغيل في حالة pending أو unknown، أرسل بطلب POST استجابة نهائية إلى https://makeagent.fast/api/agent/actions/RUN_ID/callback. أرسل عقد الاستجابة نفسه مع status: "done" أو "failed"؛ ولا تُقبل pending هنا.

تحديث عقد الاستدعاء بتاريخ 2026-10-14: وقّع maf-callback-v1: + runId + : + timestamp + . + rawBody. إذا كان الجسم يتضمن runId فيجب أن يطابق معرّف التشغيل في المسار؛ وعدم التطابق يعيد 400. التوقيعات الخاصة بتشغيل آخر أو بالصيغة السابقة غير المرتبطة تعيد 403.

import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);

استخدم سر الوكيل المحفوظ على خادمك ومعرّف التشغيل الذي استلمته في الطلب الأصلي. يستخدم الاستدعاء maf-callback-v1: وليس نطاق تسمية الطلب الصادر. يجب أن يكون فارق الطابع الزمني ضمن خمس دقائق. تعيد التوقيعات غير الصالحة 403؛ وتعيد الأجسام غير الصالحة 400؛ ويعيد التشغيل المنتهي أصلًا أو غير المتوافق 409. لا يؤدي الاستدعاء المكرر إلى استبدال النتيجة النهائية. بدّل هذا السر مع إعدادات الهوية وتوقيع نقطة النهاية لديك.

تأكيد العميل والإيصالات#

يراجع العميل المدخلات بدقة ثم يضغط تأكيد أو إلغاء على الاقتراح. تنتهي صلاحية الاقتراح بعد 15 دقيقة؛ والاقتراح الجديد للإجراء/المحادثة نفسيهما يحل محل القديم. يستخدم التأكيد رمزًا مرتبطًا بذلك التشغيل والموقع والزائر. كتابة «نعم» أو النقر على بطاقة تأكيد عامة لا يفوّض بتنفيذ التغيير. أزرار وضع التجربة غير فعّالة ولا تستدعي نقطة النهاية لديك.

على الويب، تستعلم أداة الدردشة المفتوحة بشكل دوري عن الإيصالات غير النهائية، في البداية كل خمس ثوانٍ ثم كل 30 ثانية، لمدة تصل إلى 24 ساعة. قد يظهر الإيصال بحالة: تم الطلب، في انتظار المالك، قيد التشغيل، معلّق، جارٍ التحقق من نتيجة غير معروفة، تم، فشل، مرفوض، ملغى، أو منتهي الصلاحية. فقط done يؤكد الاكتمال.

تعمل اقتراحات القنوات في المحادثات الخاصة فقط، وليس في المجموعات أو القنوات العامة. تستخدم الإيصالات المتأخرة صندوق الإرسال الدائم (outbox): تُدعم رسائل Telegram الخاصة العادية مع البوت؛ أما WhatsApp وMessenger وInstagram وTelegram Business فتتطلب رسالة واردة مسجّلة خلال 24 ساعة، ويُعاد التحقق منها وقت الإرسال. التسليم المتأخر غير متاح لاستعلامات الضيوف في Telegram ولـ Discord وKakaoTalk. قد تمنع النوافذ المغلقة والاتصالات المعطّلة التسليم؛ ومع ذلك يسجل سجل التشغيل النتيجة.

الحدود والاختبار#

استخدم نقطة نهاية خاضعة للتحكم للتحقق من التأكيد والإلغاء والموافقة والمهلة ومعالجة المفتاح المكرر والاستدعاءات النهائية. افحص سجلاتها وليس نص الإيصال فقط. يثبت وضع التجربة عدم حدوث أي كتابة خارجية؛ وهو ليس اختبارًا لتنفيذ نقطة النهاية. اختبر كل قناة خاصة تنوي استخدامها قبل الاعتماد على الإيصالات.