POST/v1/sms/purchase

شراء رقم

يشتري رقم SMS افتراضياً لاستلام رمز التحقق للخدمة المحددة.

الصلاحية المطلوبة: sms.purchaseحد الطلبات: 10 rps

المعطيات

servicestringمطلوب

معرّف الخدمة، مثل "whatsapp".

country_codestringمطلوب

رمز الدولة ISO-3166-1 من حرفين، بأحرف صغيرة.

أمثلة الكود

curl -X POST "https://samaprime.com/api/v1/sms/purchase" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"service":"example","country_code":"example"}'

الاستجابة

→ 201
{
  "data": {
    "order_id": "ord_01J8X9AABBCCDD",
    "phone_number": "+15551234567",
    "expires_at": "2026-08-10T15:02:00Z",
    "cost_usd": "0.8000",
    "cost_locked_from_balance": true
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

الأخطاء

الحالة	الرمز
400	`invalid_service` لا يوجد ربط فعّال بين هذه الخدمة والدولة.
422	`insufficient_balance` رصيد المحفظة أقل من سعر الرقم.
409	`unavailable` هذه الخدمة/الدولة لم تعد متوفرة.
409	`no_numbers` لا توجد أرقام متاحة حالياً لهذه الخدمة/الدولة.
429	`provider_rate_limited` مزوّد SMS يحدّ من الطلبات حالياً — أعد المحاولة بعد قليل.
500	`provider_error` أعاد مزوّد SMS خطأً.