توثيق API

مقدمة

واجهة Payman API هي JSON REST API. تُرسَل جميع الطلبات إلى https://payman33.com/v1 عبر HTTPS.

المصادقة

أرسل رمز الوصول الذي حصلت عليه عند إنشاء حسابك كرمز Bearer. يُعرض مرة واحدة فقط ولا يمكن إعادة إصداره، لذا حافظ على سريته ولا تضعه أبدًا في شيفرة من جهة العميل.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

إرسال رسالة

POST /messages

الحقل	النوع	الوصف
`to`	string[]	المستلمون بتنسيق E.164. حتى 10,000 في كل طلب.
`text`	string	نص الرسالة: رسالة SMS واحدة، حتى 160 حرفًا (GSM-7)، أو 70 إذا احتوى على أي حروف أخرى أو رموز تعبيرية. يُرفض النص الأطول.
`schedule_at`	string	اختياري. وقت بصيغة ISO-8601 للإرسال لاحقًا، حتى 30 يومًا مقدمًا.
`callback_url`	string	عنوان HTTPS اختياري يستقبل تقارير التسليم.

{
  "id": "msg_01J9Z3K8V2",
  "status": "queued",
  "recipients": 1,
  "segments": 1,
  "cost": 0.0063
}

أضف ترويسة Idempotency-Key لإعادة المحاولة بأمان: المفتاح نفسه خلال 24 ساعة يُرجع الاستجابة الأصلية بدلًا من الإرسال مجددًا.

حالة الرسالة

GET /messages/{id}

الحالات: queued، ثم sent، ثم delivered أو failed. تبقى الرسالة المجدولة بحالة scheduled حتى إرسالها؛ ويمكنك إلغاؤها (واسترداد الرسوم) عبر POST /messages/{id}/cancel.

Webhooks

عند وصول تقرير تسليم نرسله عبر POST إلى callback_url الخاص بك. يحمل كل طلب ترويسة X-Payman-Signature، وهي HMAC-SHA256 لمحتوى الطلب باستخدام سرّ Webhook الخاص بك (لوحة التحكم، تبويب API)، لتتمكن من التحقق منه. تُعاد محاولة التسليمات الفاشلة حتى 3 مرات.

{
  "id": "msg_01J9Z3K8V2",
  "to": "+14155550123",
  "status": "delivered",
  "delivered_at": "2026-10-09T08:12:03Z"
}

الرصيد

GET /balance

يُرجع رصيدك الحالي بعملة USDT. الأسعار مدرجة بالدولار الأمريكي؛ 1 USDT = 1 USD.

الأخطاء

HTTP	الرمز	المعنى
400	`invalid_request`	حقل مفقود أو بتنسيق غير صحيح.
401	`unauthorized`	مفتاح API مفقود أو غير صالح.
402	`insufficient_balance`	اشحن رصيدك لمواصلة الإرسال.
403	`verification_required`	بلغت الحسابات غير الموثّقة حد المستلمين لليوم.
404	`not_found`	لا توجد رسالة كهذه في حسابك.
429	`rate_limited`	طلبات كثيرة جدًا. أعد المحاولة بعد المدة المحددة في ترويسة `Retry-After`.

حدود المعدل

الحد الافتراضي هو 50 طلبًا في الثانية لكل حساب. استخدم الإرسال الجماعي (عدة أرقام في to) للحملات الكبيرة. يمكن للحسابات غير الموثّقة الإرسال إلى 500 مستلم كحد أقصى يوميًا.