مرجع API

واجهة REST لـ AgentSend. تستخدم جميع الطلبات والاستجابات JSON. العنوان الأساسي: https://api.agentsend.io.

نظرة عامة

واجهة AgentSend هي REST API تمنح وكلاءك وصولاً برمجياً إلى صناديق البريد والرسائل والمحادثات وWebhooks والنطاقات والمرفقات وإعدادات الحساب. كل جسم طلب واستجابة هو JSON.

جميع نقاط نهاية API متوفرة تحت العنوان الأساسي:

base url

https://api.agentsend.io

ⓘ

للتطوير المحلي، تتوفر API على http://localhost:3000 عند تشغيل الخادم محلياً.

المصادقة

تدعم واجهة AgentSend طريقتَي مصادقة. تحتاج واحدة فقط لكل طلب.

رمز Bearer

مرّر مفتاح API كرمز Bearer في ترويسة Authorization. هذه هي الطريقة المفضلة للطلبات من جانب الخادم.

curl

curl https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>"

ترويسة مفتاح API

بديلاً، مرّر مفتاح API مباشرةً في ترويسة x-api-key.

curl

curl https://api.agentsend.io/inboxes \
  -H "x-api-key: <your-api-key>"

⚠

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

تنسيق الطلب

أرسل أجسام الطلبات بصيغة JSON وضمّن ترويسة Content-Type: application/json على جميع الطلبات التي تحتوي على جسم.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

الترقيم

تدعم نقاط النهاية التي تُرجع قوائم معاملَي الاستعلام limit وoffset للترقيم. الحد الافتراضي هو 20.

المعامل	النوع	الافتراضي	الوصف
`limit`	integer	`20`	العدد الأقصى للعناصر المطلوب إرجاعها. الحد الأقصى 100.
`offset`	integer	`0`	عدد العناصر المطلوب تخطيها قبل إرجاع النتائج.

تتضمن جميع استجابات القوائم مصفوفة data وعدداً total بكل السجلات المطابقة:

json — paginated response

{
  "data": [ /* array of objects */ ],
  "total": 142
}

لجلب الصفحة التالية، زد offset بقيمة limit. مثلاً للحصول على الصفحة 3 بحجم صفحة 20: ?limit=20&offset=40.

معالجة الأخطاء

تُرجع الأخطاء جسم JSON مع كائن error يحتوي code قابل للقراءة آلياً، وmessage قابل للقراءة بشرياً، وstatus HTTP.

json — error response

{
  "error": {
    "code": "INBOX_NOT_FOUND",
    "message": "No inbox found with that ID.",
    "status": 404
  }
}

رموز حالة HTTP الشائعة التي تُرجعها API:

الحالة	المعنى
`400`	طلب غير صالح — جسم الطلب يفتقر إلى حقول مطلوبة أو يحتوي قيماً غير صالحة.
`401`	غير مصرَّح — لم يُقدَّم مفتاح API، أو المفتاح غير صالح.
`403`	محظور — مفتاح API لا يملك إذناً لتنفيذ هذا الإجراء.
`404`	غير موجود — المورد المطلوب غير موجود.
`409`	تعارض — المورد موجود بالفعل أو الطلب يتعارض مع الحالة الحالية.
`429`	طلبات كثيرة جداً — تجاوزت حد المعدل. تراجع وأعد المحاولة.
`500`	خطأ داخلي في الخادم — حدث خطأ من جانب AgentSend.

حدود المعدل

جميع نقاط نهاية API محدودة المعدل لحماية استقرار المنصة. عند تجاوز الحد، تُرجع API استجابة 429 Too Many Requests.

تتضمن كل استجابة API ترويسات حد المعدل لتتمكن من تتبع استخدامك:

الترويسة	الوصف
`X-RateLimit-Limit`	العدد الأقصى للطلبات المسموح بها في النافذة الحالية.
`X-RateLimit-Remaining`	عدد الطلبات المتبقية في النافذة الحالية.
`X-RateLimit-Reset`	طابع Unix الزمني لوقت إعادة تعيين نافذة حد المعدل.

💡

استخدم تراجعاً أُسياً عند إعادة المحاولة بعد استجابة 429. انتظر الوقت المُشار إليه بـX-RateLimit-Reset قبل إرسال طلبات إضافية.

المعاودة

يمكن لطلبات POST تضمين ترويسة Idempotency-Key لإعادة محاولة الطلبات بأمان دون إنشاء موارد مكررة. إذا استُلم طلب بنفس مفتاح المعاودة خلال نافذة المعاودة، تُرجع الاستجابة الأصلية بدلاً من إنشاء مورد جديد.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-abc123" \
  -d '{"displayName": "Support Agent"}'