REST API قوية وبسيطة

ادمج، وأتمِت، وسلّم بثقة.

أرسل رسائل SMS، وأجرِ مكالمات بمعرّف مخصص، وتحقّق من رصيدك، واجلب الأسعار المباشرة من الكود الخاص بك. خمس نقاط نهاية، ومفتاح واحد، وJSON في الطلب والاستجابة — بالأسعار والرصيد نفسيهما في لوحة التحكم.

ساحة تجربة API

الطلب

curl https://app.spoofcallerid.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
curl https://app.spoofcallerid.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
curl https://app.spoofcallerid.com/v1/prices?type=all \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
curl -X POST https://app.spoofcallerid.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "text": "Your code is 4821",
    "sender_id": "Spoof",
    "country": "GB"
  }'
curl -X POST https://app.spoofcallerid.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "caller_id": "+18005550199",
    "to_country": "GB",
    "record": false
  }'
curl -X POST https://app.spoofcallerid.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "text": "Your code is 4821",
    "sender_id": "Spoof",
    "country": "GB"
  }'

الاستجابة

{
    "id": 1042,
    "username": "you",
    "email": "[email protected]",
    "balance": 25.5,
    "currency": "EUR",
    "status": "active"
}
{
    "balance": 25.5,
    "currency": "EUR"
}
{
    "success": true,
    "type": "all",
    "count": 200,
    "cached_ttl": 3600,
    "data": [
        {
            "country": "United Kingdom",
            "iso": "GB",
            "prefix": "44",
            "call": 0.1,
            "call_initblock": 1,
            "call_billingblock": 1,
            "call_tiers": [
                {
                    "rate": 0.1,
                    "routes": 1
                },
                {
                    "rate": 0.4,
                    "routes": 1
                },
                {
                    "rate": 0.85,
                    "routes": 1
                }
            ],
            "sms": 0.0906,
            "sms_routes": [
                {
                    "name": "Route 1",
                    "rate": 0.0906
                },
                {
                    "name": "Route 2",
                    "rate": 0.0924
                }
            ],
            "hlr": null,
            "currency": "EUR"
        }
    ]
}
{
    "success": true,
    "message": "SMS sent successfully.",
    "data": {
        "cost": 0.0906,
        "newBalance": 25.4094,
        "segments": 1,
        "encoding": "gsm7",
        "route": "",
        "batchId": "7f3c2a91"
    }
}
{
    "success": true,
    "message": "Call placed successfully.",
    "data": {
        "id": 318,
        "status": "dialing",
        "cost": 0.5,
        "newBalance": 25.0,
        "currentBalance": 25.0,
        "estimatedMinutes": 5,
        "toNumber": "+447700900123",
        "displayNumber": "+18005550199",
        "ami_ref": "spoof_1042_1763190000"
    }
}
{
    "error": {
        "code": "insufficient_balance",
        "message": "Insufficient balance.",
        "details": {
            "cost": 0.0906,
            "balance": 0.02
        }
    }
}
تنبيه أمني مهم

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

المصادقة
Bearer

يحمل كل طلب المفتاح والسر في ترويسة واحدة، يفصل بينهما نقطتان (:). الطلبات والاستجابات بصيغة JSON عبر HTTPS.

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

الرابط الأساسي: https://app.spoofcallerid.com/v1

عرض الحساب
GET /v1/me

يُعيد الحساب المالك للمفتاح: المعرّف، واسم المستخدم، والبريد الإلكتروني، والرصيد، والحالة.

curl https://app.spoofcallerid.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
{
    "id": 1042,
    "username": "you",
    "email": "[email protected]",
    "balance": 25.5,
    "currency": "EUR",
    "status": "active"
}
عرض الرصيد
GET /v1/balance

رصيدك الحالي باليورو. طلب خفيف — استخدمه قبل أي إرسال كبير.

curl https://app.spoofcallerid.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
{
    "balance": 25.5,
    "currency": "EUR"
}
عرض الأسعار
GET /v1/prices

أسعار المكالمات ورسائل SMS المباشرة لكل وجهة، وهي القائمة نفسها في صفحة التغطية والأسعار. تُخزَّن مؤقتًا لمدة ساعة.

المعاملات:
  • type: اختياري. all (افتراضي)، أو sms أو voice.
curl https://app.spoofcallerid.com/v1/prices?type=all \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
{
    "success": true,
    "type": "all",
    "count": 200,
    "cached_ttl": 3600,
    "data": [
        {
            "country": "United Kingdom",
            "iso": "GB",
            "prefix": "44",
            "call": 0.1,
            "call_initblock": 1,
            "call_billingblock": 1,
            "call_tiers": [
                {
                    "rate": 0.1,
                    "routes": 1
                },
                {
                    "rate": 0.4,
                    "routes": 1
                },
                {
                    "rate": 0.85,
                    "routes": 1
                }
            ],
            "sms": 0.0906,
            "sms_routes": [
                {
                    "name": "Route 1",
                    "rate": 0.0906
                },
                {
                    "name": "Route 2",
                    "rate": 0.0924
                }
            ],
            "hlr": null,
            "currency": "EUR"
        }
    ]
}
إرسال SMS
POST /v1/sms

يرسل رسالة SMS واحدة بمعرّف المرسل الذي تختاره، ويخصم من رصيدك عن كل جزء من الرسالة.

المعاملات:
  • to: مطلوب. رقم المستلم مع رمز الدولة، مثل +447700900123.
  • text: مطلوب. نص الرسالة، حتى 160 حرفًا.
  • sender_id: مطلوب. الاسم أو الرقم الذي يظهر كمرسل، من 1 إلى 20 حرفًا أو رقمًا.
  • country: اختياري. رمز الدولة بصيغة ISO (مثل GB) عندما لا يتضمن to رمز الدولة.
  • route: اختياري. مسار محدد للوجهة؛ يُستخدم المسار الأرخص افتراضيًا.
curl -X POST https://app.spoofcallerid.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "text": "Your code is 4821",
    "sender_id": "Spoof",
    "country": "GB"
  }'
{
    "success": true,
    "message": "SMS sent successfully.",
    "data": {
        "cost": 0.0906,
        "newBalance": 25.4094,
        "segments": 1,
        "encoding": "gsm7",
        "route": "",
        "batchId": "7f3c2a91"
    }
}
إجراء مكالمة بمعرّف مخصص
POST /v1/calls

يُجري مكالمة تُظهر معرّف المتصل الذي تختاره. تُحجز التكلفة التقديرية من رصيدك عند بدء المكالمة.

المعاملات:
  • to: مطلوب. الرقم المراد الاتصال به، بالصيغة الدولية أو بالصيغة المحلية مع to_country.
  • caller_id: مطلوب. الرقم الذي سيظهر للشخص الذي تتصل به.
  • to_country: اختياري. رمز ISO لدولة to، مثل GB.
  • caller_country: اختياري. رمز ISO لدولة caller_id.
  • record: اختياري. true لتسجيل المكالمة. القيمة الافتراضية false.
  • plan: اختياري. معرّف خطة الاتصال. لكل خطة سعرها ووحدة احتسابها؛ الافتراضي Worldwide.
curl -X POST https://app.spoofcallerid.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "caller_id": "+18005550199",
    "to_country": "GB",
    "record": false
  }'
{
    "success": true,
    "message": "Call placed successfully.",
    "data": {
        "id": 318,
        "status": "dialing",
        "cost": 0.5,
        "newBalance": 25.0,
        "currentBalance": 25.0,
        "estimatedMinutes": 5,
        "toNumber": "+447700900123",
        "displayNumber": "+18005550199",
        "ami_ref": "spoof_1042_1763190000"
    }
}
الأخطاء
4xx / 5xx

تُعيد كل عملية فاشلة رمز حالة HTTP المبيّن أدناه ونص JSON يتضمن قيمة error.code ثابتة يمكنك الاعتماد عليها في منطق برنامجك.

  • invalid_request 400 — نص الطلب ليس JSON صالحًا أو أحد الحقول من نوع خاطئ.
  • unauthorized 401 — ترويسة Authorization مفقودة أو مشوّهة، أو المفتاح/السر غير صحيح.
  • insufficient_balance 402 — رصيدك لا يغطي التكلفة. يحتوي error.details على التكلفة والرصيد.
  • not_found 404 — نقطة النهاية غير موجودة. تحقّق من المسار ومن البادئة /v1.
  • method_not_allowed 405 — طريقة HTTP خاطئة؛ تُظهر ترويسة Allow الطريقة الصحيحة.
  • validation_failed 422 — حقل مفقود أو غير صالح؛ يوضّح error.message أيّ حقل.
  • internal_error 500 — حدث خلل من جانبنا. أعد المحاولة، ثم تواصل مع الدعم.
  • provider_rejected 502 — رفض المشغّل الرسالة أو المكالمة؛ ولم يُخصم أي مبلغ.
  • service_unavailable 503 — إحدى الخدمات المعتمَد عليها متوقفة مؤقتًا. أعد المحاولة مع زيادة فترات الانتظار تدريجيًا.
{
    "error": {
        "code": "insufficient_balance",
        "message": "Insufficient balance.",
        "details": {
            "cost": 0.0906,
            "balance": 0.02
        }
    }
}
اربط مساعدك الذكي (MCP)
5 tools

يحوّل خادم MCP من Spoofcallerid كل نقطة نهاية إلى أداة يستخدمها Claude أو أي عميل MCP: get_account وget_balance وget_prices وsend_sms وmake_spoof_call. ملف واحد، دون أي تبعيات، Node.js 18+. والأداتان اللتان تستهلكان الرصيد تطلبان التأكيد أولًا.

تنزيل خادم MCP · ملف التعريف JSON

{
    "mcpServers": {
        "spoofcallerid": {
            "command": "node",
            "args": [
                "/path/to/spoofcallerid-mcp.mjs"
            ],
            "env": {
                "SPOOFCALLERID_API_KEY": "YOUR_API_KEY:YOUR_API_SECRET"
            }
        }
    }
}

الأسئلة الشائعة

من أين أحصل على مفتاح API؟
سجّل الدخول إلى لوحة التحكم وافتح الحساب ← API والمفاتيح. تؤدي إعادة الإنشاء إلى إنشاء مفتاح وسر جديدين؛ يُعرض السر مرة واحدة فقط ويتوقف الزوج القديم عن العمل فورًا.
كيف تتم المصادقة؟
أرسل Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET مع كل طلب. احتفظ بالسر على خادمك — ولا تضعه أبدًا في متصفح أو تطبيق جوال.
كم تبلغ تكلفة الطلب الواحد؟
قراءة بيانات حسابك ورصيدك والأسعار مجانية. يُحتسب على POST /v1/sms وPOST /v1/calls الأسعار نفسها المعتمدة في لوحة التحكم، والمعروضة في صفحة التغطية والأسعار وفي GET /v1/prices.
ما الحد الأقصى لطول رسالة SMS؟
حتى 160 حرفًا لكل طلب. يتسع نص GSM-7 لـ 160 حرفًا في جزء واحد؛ أما الرموز التعبيرية أو الأحرف غير اللاتينية فتحوّل الترميز إلى Unicode الذي يتسع لـ 70 حرفًا لكل جزء، ويُحتسب كل جزء على حدة.
هل يمكن لمساعد ذكاء اصطناعي استخدام API؟
نعم. نزّل خادم MCP من Spoofcallerid وزوّده بمفتاحك، وسيتمكن Claude أو أي عميل MCP من التحقق من رصيدك والأسعار، وإرسال رسائل SMS، وإجراء المكالمات. وتطلب الأدوات التي تستهلك الرصيد التأكيد أولًا.