أمثلة cURL / SDK

تستخدم كل الأمثلة عنوان URL الأساسي العام:

https://api.zelnum.com/api/v1

استبدل YOUR_KEY_HERE بمفتاح من المصادقة، وخُذ معرّفات المنتجات من منتجات الوقت الفعلي — فالمعرّفات أدناه أمثلة وتتغيّر عند إضافة منتجات.

رقم هاتف واحد، منتج واحد

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9f3f-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47]}'

country اختياري عندما يكون الرقم بصيغة E.164 كاملة بالفعل. وأدرجه عندما ترسل رقمًا محليًا.

رقم هاتف واحد، عدة منتجات

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: 5c2f1a90-6b7d-4e8f-9a01-2b3c4d5e6f70" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47,50,51]}'

ثلاثة منتجات، وrequest_id واحد، وثلاثة مدخلات في results، وثلاثة احتسابات. راجع منتجات الوقت الفعلي للحد الأقصى البالغ عشرة معرّفات.

عنوان بريد إلكتروني واحد

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: 0d9c8b7a-6543-4321-fedc-ba9876543210" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"user@example.com","product_ids":[49]}'

لاحظ غياب country — فمنتجات البريد الإلكتروني ترفضه.

قراءة ما تحتاجه فقط

curl -s -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: 3a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","product_ids":[47,50]}' \
  | jq '{status, charged: .total_charged, items: [.results[] | {product: .product, result: .result, billed: .billing_status}]}'

افحص billing_status لكل مدخل، لا حالة HTTP وحدها — فقد تحمل الاستجابة 200 مدخلات مستردة. راجع الفوترة والاسترداد.

حلقة إعادة محاولة لا يمكن أن تحتسب مرتين

الغاية من Idempotency-Key هي أن هذا السكربت آمن للتشغيل مرتين:

KEY=$(uuidgen)
BODY='{"identifier":"+8613800138000","country":"CN","product_ids":[47]}'

for attempt in 1 2 3; do
  response=$(curl -s -w '\n%{http_code}' -X POST \
    "https://api.zelnum.com/api/v1/realtime/check/phone" \
    -H "X-API-Key: YOUR_KEY_HERE" \
    -H "Idempotency-Key: $KEY" \
    -H "Content-Type: application/json" \
    -d "$BODY")

  code=$(printf '%s' "$response" | tail -n1)
  printf '%s' "$response" | sed '$d'

  case "$code" in
    200) exit 0 ;;
    # نتيجة غير مؤكدة: المفتاح هو الغاية كلها. أعد إرسال المتن نفسه.
    500|000) sleep 2 ;;
    # لا يزال قيد التنفيذ، أو مُقيَّد: احترم Retry-After وأبقِ المفتاح نفسه.
    409|429) sleep "$(printf '%s' "$response" | sed '$d' | jq -r '.retry_after // 2')" ;;
    *) exit 1 ;;
  esac
done

لا تولّد مفتاحًا جديدًا أبدًا لإعادة محاولة طلب لم تلاحظ نتيجته — فهذه بالضبط طريقة الدفع مقابل فحص واحد مرتين. راجع عدم التكرار وإعادة المحاولة.

شكل الاستجابة

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-13T10:00:00Z",
      "error_code": null
    }
  ]
}

للاطلاع على المرجع الكامل للحقول راجع تنسيق الاستجابة.