API
إعادة توجيه النماذج (webhook)
استقبل في الـ API الخاصة بك كل نموذج مكتمل
# إعادة توجيه النماذج (webhook) > استقبل في الـ API الخاصة بك كل نموذج مكتمل - الصفحة: https://tbit.app/ar/docs/api/forms-webhook - عنوان URL الأساسي: `https://rest-api.tbit.app/v1` - المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`) ## نظرة عامة عندما يُكمل شخص نموذجًا داخل المحادثة، يمكن لـ TBit استدعاء الـ API الخاصة بك بالإجابات. هناك وضعان. التحقق ثم إعادة التوجيه (موصى به عندما يطلب النموذج مستندات): يراجع TBit المستندات المرفقة بالرؤية الحاسوبية، ويطابقها مع ما صرّح به الشخص، ويخبره بالنتيجة، ولا يرسل POST بالملف إلى عنوان URL الخاص بك مع إعادة المحاولة إلا إذا تطابق كل شيء. الاستدعاء المباشر: يرسل TBit قيم النموذج عبر POST إلى عنوان URL الخاص بك فور اكتماله، دون تحقق ودون إعادة محاولة. ## طريقة الإعداد أيّ من هذه المداخل الثلاثة يكتب الإعداد نفسه في النموذج (إجراء الإغلاق الخاص به): - Canvas (newui.tbit.app): النماذج ← افتح صف النموذج ← «إعادة التوجيه عند الانتهاء…». يطلب منك نموذج معبّأ مسبقًا الوضع، وعنوان URL الوجهة، ورمز token اختياريًا، وملف الـ payload. - MCP (Claude وChatGPT…): manage_form مع action=set_forward، وform_id من list_forms، وmode وurl وtoken وprofile. يُقترح التغيير وأنت تؤكده. - تطبيق المنصة: النماذج ← تعديل ← إجراء الإغلاق ← API. هذه هي الواجهة منخفضة المستوى: عنوان URL لمدقق المستندات، وbearer بسرّ TBit، وترويسات X-Tbit-Forward-*. ## مثال: الإعداد من الـ MCP ```json manage_form { "action": "set_forward", "form_id": "6917da72ed0bc91ea5532858", "mode": "validate_forward", "url": "https://api.tunegocio.com/tbit/perfiles", "token": "<الـ bearer الخاص بك>", "profile": "generic" } ``` ## الوضع 1 · التحقق من المستندات ثم إعادة التوجيه ### سير العملية 1. يُكمل الشخص النموذج (مع حقول ملفات للمستندات). 2. يقرأ TBit كل مستند، ويستخرج الاسم والرقم، ويطابقهما مع ما صُرّح به. 3. يتلقى الشخص رسالة: كل شيء متطابق، أو هناك اختلاف (وما الذي يجب إعادة إرساله)، أو تعذّرت قراءة الملف. 4. إذا كان الحكم MATCH، يرسل TBit طلب POST إلى عنوان URL الخاص بك. ### الترويسات التي نرسلها | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <الـ token الذي أعددته> (فقط إذا وُجد token) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <معرّف الإجابة، لإزالة التكرار> | ### Payload (ملف generic) يحمل fields كل حقل تمت الإجابة عنه باسمه في النموذج؛ ويحمل document_validation الحكم لكل مستند. إذا بنى TBit ملفًا خاصًا لشركتك، يتبع الـ body عقد البيانات ذاك، واسم الملف هو الذي أُعطي لك. ### إعادة المحاولة وعدم التكرار (idempotency) أجب بـ 2xx بأسرع ما يمكن (المهلة 10 ثوانٍ). عند 500 أو 502 أو 503 أو 504 أو خطأ في الشبكة، يعيد TBit المحاولة بعد 30 ثانية، ثم دقيقتين، ثم 10 دقائق، ثم ساعة. الرموز الأخرى لا تُعاد محاولتها. تعيش محاولات الإعادة في الذاكرة: إذا أُعيد تشغيل المحرك في المنتصف تضيع، لذا صمّم نقطة النهاية لديك على أساس at-least-once وأزِل التكرار باستخدام formDataId (يأتي أيضًا في ترويسة X-Tbit-Form-Data-Id). ```json { "formDataId": "6aabbe45706082120e74fc75", "agentId": "6aaab0521c2b87a579ccc624", "activityId": "6aabbe3c58181a93243f7298", "fields": { "الاسم الكامل": "آنا بيريز", "رقم الهوية": "1032456789", "الإنفاق على الطعام": 900, "صورة الهوية": { "kind": "file", "url": "https://api.tbit.app/media/…/dni.jpeg" } }, "document_validation": { "verdict": "MATCH", "results": [ { "field": "صورة الهوية", "document_kind": "dni", "verdict": "MATCH", "checks": { "full_name": true, "document_number": true } } ] } } ``` ## الوضع 2 · الاستدعاء المباشر فور اكتمال النموذج، يرسل TBit عبر POST كائن JSON فيه مفتاح لكل حقل (اسمه في النموذج) إضافة إلى formId وagentId وformDataId. المصادقة هي التي تختارها: Bearer (Authorization: Bearer …)، أو Basic (Authorization: Basic …)، أو API key (ترويسة X-API-Key)، إضافة إلى أي ترويسات تحددها. لا توجد إعادة محاولة: الاستدعاء الفاشل يبقى فاشلًا. ```json { "الاسم الكامل": "آنا بيريز", "رقم الهوية": "1032456789", "الإنفاق على الطعام": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## التحقق من الاستدعاءات يُسجَّل كل استدعاء مع طلبه واستجابته ورمز HTTP وعدد المحاولات. يراها فريق TBit في لوحة المطوّر داخل الـ Canvas ويمكنه مراجعتها معك؛ ولسجلاتك الخاصة، سجّل formDataId من جهتك.عندما يُكمل شخص نموذجًا داخل المحادثة، يمكن لـ TBit استدعاء الـ API الخاصة بك بالإجابات. هناك وضعان. التحقق ثم إعادة التوجيه (موصى به عندما يطلب النموذج مستندات): يراجع TBit المستندات المرفقة بالرؤية الحاسوبية، ويطابقها مع ما صرّح به الشخص، ويخبره بالنتيجة، ولا يرسل POST بالملف إلى عنوان URL الخاص بك مع إعادة المحاولة إلا إذا تطابق كل شيء. الاستدعاء المباشر: يرسل TBit قيم النموذج عبر POST إلى عنوان URL الخاص بك فور اكتماله، دون تحقق ودون إعادة محاولة.
أيّ من هذه المداخل الثلاثة يكتب الإعداد نفسه في النموذج (إجراء الإغلاق الخاص به):
- Canvas (newui.tbit.app): النماذج ← افتح صف النموذج ← «إعادة التوجيه عند الانتهاء…». يطلب منك نموذج معبّأ مسبقًا الوضع، وعنوان URL الوجهة، ورمز token اختياريًا، وملف الـ payload.
- MCP (Claude وChatGPT…): manage_form مع action=set_forward، وform_id من list_forms، وmode وurl وtoken وprofile. يُقترح التغيير وأنت تؤكده.
- تطبيق المنصة: النماذج ← تعديل ← إجراء الإغلاق ← API. هذه هي الواجهة منخفضة المستوى: عنوان URL لمدقق المستندات، وbearer بسرّ TBit، وترويسات X-Tbit-Forward-*.
manage_form
{
"action": "set_forward",
"form_id": "6917da72ed0bc91ea5532858",
"mode": "validate_forward",
"url": "https://api.tunegocio.com/tbit/perfiles",
"token": "<الـ bearer الخاص بك>",
"profile": "generic"
}سير العملية
1. يُكمل الشخص النموذج (مع حقول ملفات للمستندات). 2. يقرأ TBit كل مستند، ويستخرج الاسم والرقم، ويطابقهما مع ما صُرّح به. 3. يتلقى الشخص رسالة: كل شيء متطابق، أو هناك اختلاف (وما الذي يجب إعادة إرساله)، أو تعذّرت قراءة الملف. 4. إذا كان الحكم MATCH، يرسل TBit طلب POST إلى عنوان URL الخاص بك.
الترويسات التي نرسلها
Content-Type | application/json |
Authorization | Bearer <الـ token الذي أعددته> (فقط إذا وُجد token) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <معرّف الإجابة، لإزالة التكرار> |
Payload (ملف generic)
يحمل fields كل حقل تمت الإجابة عنه باسمه في النموذج؛ ويحمل document_validation الحكم لكل مستند. إذا بنى TBit ملفًا خاصًا لشركتك، يتبع الـ body عقد البيانات ذاك، واسم الملف هو الذي أُعطي لك.
إعادة المحاولة وعدم التكرار (idempotency)
أجب بـ 2xx بأسرع ما يمكن (المهلة 10 ثوانٍ). عند 500 أو 502 أو 503 أو 504 أو خطأ في الشبكة، يعيد TBit المحاولة بعد 30 ثانية، ثم دقيقتين، ثم 10 دقائق، ثم ساعة. الرموز الأخرى لا تُعاد محاولتها. تعيش محاولات الإعادة في الذاكرة: إذا أُعيد تشغيل المحرك في المنتصف تضيع، لذا صمّم نقطة النهاية لديك على أساس at-least-once وأزِل التكرار باستخدام formDataId (يأتي أيضًا في ترويسة X-Tbit-Form-Data-Id).
{
"formDataId": "6aabbe45706082120e74fc75",
"agentId": "6aaab0521c2b87a579ccc624",
"activityId": "6aabbe3c58181a93243f7298",
"fields": {
"الاسم الكامل": "آنا بيريز",
"رقم الهوية": "1032456789",
"الإنفاق على الطعام": 900,
"صورة الهوية": { "kind": "file", "url": "https://api.tbit.app/media/…/dni.jpeg" }
},
"document_validation": {
"verdict": "MATCH",
"results": [
{ "field": "صورة الهوية", "document_kind": "dni", "verdict": "MATCH",
"checks": { "full_name": true, "document_number": true } }
]
}
}فور اكتمال النموذج، يرسل TBit عبر POST كائن JSON فيه مفتاح لكل حقل (اسمه في النموذج) إضافة إلى formId وagentId وformDataId. المصادقة هي التي تختارها: Bearer (Authorization: Bearer …)، أو Basic (Authorization: Basic …)، أو API key (ترويسة X-API-Key)، إضافة إلى أي ترويسات تحددها. لا توجد إعادة محاولة: الاستدعاء الفاشل يبقى فاشلًا.
{
"الاسم الكامل": "آنا بيريز",
"رقم الهوية": "1032456789",
"الإنفاق على الطعام": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}يُسجَّل كل استدعاء مع طلبه واستجابته ورمز HTTP وعدد المحاولات. يراها فريق TBit في لوحة المطوّر داخل الـ Canvas ويمكنه مراجعتها معك؛ ولسجلاتك الخاصة، سجّل formDataId من جهتك.