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_request400 — نص الطلب ليس JSON صالحًا أو أحد الحقول من نوع خاطئ.unauthorized401 — ترويسة Authorization مفقودة أو مشوّهة، أو المفتاح/السر غير صحيح.insufficient_balance402 — رصيدك لا يغطي التكلفة. يحتويerror.detailsعلى التكلفة والرصيد.not_found404 — نقطة النهاية غير موجودة. تحقّق من المسار ومن البادئة/v1.method_not_allowed405 — طريقة HTTP خاطئة؛ تُظهر ترويسةAllowالطريقة الصحيحة.validation_failed422 — حقل مفقود أو غير صالح؛ يوضّحerror.messageأيّ حقل.internal_error500 — حدث خلل من جانبنا. أعد المحاولة، ثم تواصل مع الدعم.provider_rejected502 — رفض المشغّل الرسالة أو المكالمة؛ ولم يُخصم أي مبلغ.service_unavailable503 — إحدى الخدمات المعتمَد عليها متوقفة مؤقتًا. أعد المحاولة مع زيادة فترات الانتظار تدريجيًا.
{
"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؟
كيف تتم المصادقة؟
Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET مع كل طلب. احتفظ بالسر على خادمك — ولا تضعه أبدًا في متصفح أو تطبيق جوال.كم تبلغ تكلفة الطلب الواحد؟
POST /v1/sms وPOST /v1/calls الأسعار نفسها المعتمدة في لوحة التحكم، والمعروضة في صفحة التغطية والأسعار وفي GET /v1/prices.