المطورين

Quickstart - اتصل بـ API من الخادم الخاص بك

قم بالمطالبة بوضع الحماية، وقم بتخزين مفتاح `esk_test_`، وقم بتأكيده، وإنشاء مستند من قالب، وإرساله. تستخدم الرموز المميزة لجلسة التوقيع نفس المفتاح. تم تسجيل Webhooks في تطبيق المشرف.

قبل أن تبدأ

أنت بحاجة إلى محطة طرفية تحتوي على `curl` و`jq`، بالإضافة إلى صندوق بريد إلكتروني يمكنك التحكم فيه. مفتاح وضع الحماية هو `esk_test_...`. مفتاح الإنتاج هو `esk_live_...`. أرسله كـ "تفويض: حامل". يأتي المستأجر من المفتاح، لذا لا ترسل "x-tenant-id".

يتضمن مفتاح وضع الحماية "التكاملات: zapier" و"التوقيع: الكتابة". يستخدم التحميل ومعالج المغلف وتسجيل webhook جلسة الإدارة بعد تسجيل الدخول. يستخدم الخادم الخاص بك المفتاح للمكالمات أدناه.

أربعة مكالمات للخادم، ثم webhook في تطبيق المسؤول

  1. 1

    المطالبة بوضع الحماية الخاص بك

    POST /api/auth/register with `mode: sandbox`. The response includes a full `esk_test_…` key, shown once, plus `demoCustomerId`. When seeding succeeds it also includes `sampleTemplateId`.

  2. 2

    تأكيد المفتاح

    GET /api/v1/zapier/auth/test with the key. Expected output: HTTP 200 and `{ success: true, data: { tenantId, tenantName, zapierEnabled: true } }`.

  3. 3

    أنشئ مستندًا وأرسله

    POST /api/v1/zapier/actions/create-from-template with `sampleTemplateId`, then POST /api/v1/zapier/actions/send-for-signing with the returned `documentId`. The signer receives the link by email.

  4. 4

    قم بتسجيل webhook في المشرف

    قم بتسجيل الدخول وافتح المسؤول → المطور → Webhooks. احفظ سر التوقيع. تستخدم عمليات التسليم `X-Endorsed-Signature`. خطوات التحقق موجودة في دليل webhooks. افحص المحاولات في المسؤول → المطور → وحدة التحكم.

الخطوة 1 - المطالبة بوضع الحماية

المتطلبات الأساسية: عنوان بريد إلكتروني وكلمة مرور مكونة من 8 أحرف. الإخراج المتوقع: HTTP 201 مع بدء تشغيل `data.sandbox.apiKey` `esk_test_`.

bash
curl -sS -X POST https://api.endorsedsign.com/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantName": "Acme Dev Sandbox",
    "adminEmail": "you@acme.example",
    "password": "your-strong-password",
    "mode": "sandbox"
  }' | tee sandbox.json | jq '.data.sandbox'

# → {
#     "apiKey": "esk_test_…",
#     "keyPrefix": "esk_test_…",
#     "keyId": "…",
#     "scopes": ["signing:write", "integrations:zapier", …],
#     "demoCustomerId": "sandbox-signer-acme-dev-sandbox",
#     "demoCustomerName": "Sandbox Signer",
#     "sampleTemplateId": "…",
#     "expiresAt": "2026-…"
#   }

export ENDORSED_API_KEY="$(jq -r '.data.sandbox.apiKey' sandbox.json)"
export ENDORSED_TEMPLATE_ID="$(jq -r '.data.sandbox.sampleTemplateId // empty' sandbox.json)"

قم بتخزين المفتاح في مدير سر الخادم الخاص بك. التحقق من البريد الإلكتروني يفتح وحدة تحكم المشرف. يعمل المفتاح للمكالمات على هذه الصفحة بمجرد صدوره.

الخطوة 2 - تأكيد المفتاح

المتطلبات الأساسية: `$ENDORSED_API_KEY` من الخطوة 1. يحتوي مفتاح وضع الحماية بالفعل على `التكاملات: zapier`. الإخراج المتوقع: HTTP 200 واسم المستأجر الخاص بك.

bash
curl -sS https://api.endorsedsign.com/api/v1/zapier/auth/test \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  | jq '{ success, tenantId: .data.tenantId, tenantName: .data.tenantName, zapierEnabled: .data.zapierEnabled }'

المفتاح المفقود أو المشوه هو 401. المفتاح الصالح بدون `التكامل: zapier` هو 403. لا ترسل `X-Data-Mode`: `esk_test_` يحدد بالفعل بيانات الاختبار.

الخطوة 3 - أنشئ مستندًا من قالب الحماية وأرسله

المتطلبات الأساسية: `$ENDORSED_API_KEY` و`$ENDORSED_TEMPLATE_ID` غير فارغ. إذا كان `sampleTemplateId` فارغًا، فقم بإنشاء قالب في تطبيق المسؤول والصق المعرف الخاص به. المخرجات المتوقعة: HTTP 201 مع `data.documentId`، ثم استجابة إرسال مع `الحالة: "link-sent"`.

bash
curl -sS -X POST https://api.endorsedsign.com/api/v1/zapier/actions/create-from-template \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{
    \"templateId\": \"$ENDORSED_TEMPLATE_ID\",
    \"recipientEmail\": \"you@acme.example\",
    \"recipientName\": \"Sandbox Signer\"
  }" | tee created.json | jq '.data | { documentId, customerId, status }'

export ENDORSED_DOCUMENT_ID="$(jq -r '.data.documentId' created.json)"

curl -sS -X POST https://api.endorsedsign.com/api/v1/zapier/actions/send-for-signing \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{
    \"documentId\": \"$ENDORSED_DOCUMENT_ID\",
    \"channel\": \"email\",
    \"subject\": \"Please sign\"
  }" | jq '.data | { documentId, status, channel, shareLinkExpiresAt }'

يتم إرسال رابط التوقيع عبر البريد الإلكتروني إلى "recipientEmail". تحمل استجابة JSON معرف المستند وحالته وانتهاء الارتباط. افتح البريد الإلكتروني لإنهاء التوقيع، ثم شاهد "document.signed" على webhook الذي قمت بالتسجيل فيه في Admin.

اصنع رمزًا مميزًا لجلسة التوقيع

المتطلبات الأساسية: `$ENDORSED_API_KEY` مع `signing:write` (مضمن في مفتاح وضع الحماية) ومعرف جلسة التوقيع من جلسة قمت بإنشائها بالفعل. المخرجات المتوقعة: HTTP 201 مع رمز مميز `st_...` لمرة واحدة.

bash
curl -sS -X POST "https://api.endorsedsign.com/api/v1/signing-sessions/$ENDORSED_SESSION_ID/tokens" \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "scope": "embed", "ttl_seconds": 300 }' \
  | jq '{ token, expires_at, scope }'

اليد `st_...` لتضمين المتصفح. احتفظ بـ esk_... على الخادم. تعليمات الاسترداد موجودة في صفحة تضمين العناصر.

عندما يحدث خطأ ما

هل أنت مستعد للتعمق أكثر؟

بمجرد حصولك على مستند موقع من طرف إلى طرف، قم بتوصيله بمساحات السطح أدناه للحصول على الشريحة التالية من التكامل.

REST API مرجعWebhook العقد + التوقيعات