HTTP API v1

مقدمة

يعتمد NoKYCNumber API على بنية REST. نستخدم روابط URL موجّهة للموارد يمكن التنبؤ بها، ونقبل ونُعيد أجسام مشفّرة بـ JSON، ونستخدم رموز استجابة HTTP القياسية والمصادقة والأفعال.

عنوان URL الأساسي

https://api.nokycnumber.com/v1/

يجب إرسال جميع الطلبات عبر HTTPS. ستفشل المكالمات عبر HTTP العادي بخطأ 301 Moved Permanently. وستفشل الطلبات غير المصادق عليها بخطأ 401 Unauthenticated.

اصطلاح JSON

• تستخدم جميع الطلبات ذات المحتوى Content-Type: application/json. يتم رفض المحتوى المشفَّر بصيغة النماذج بخطأ 415.
• تُعاد الطوابع الزمنية كسلاسل ISO-8601 UTC (2026-04-26T14:23:00Z) وتُقبل بالتنسيق ذاته.
• تُعاد أرقام الهاتف بصيغة E.164 مع + في البداية (+33647189022) وتُعرض بشكل منسّق في display عند الاقتضاء.
• تبدأ معرّفات الكائنات بادئةً بمواردها: num_، call_، sms_، vm_، whk_، evt_.

المصادقة

قم بالمصادقة باستخدام مفتاح bearer صادر من لوحتك ضمن الإعدادات → مفاتيح API. يوجد نوعان من المفاتيح:

• sk_live_… — سر جانب الخادم. صلاحيات قراءة/كتابة كاملة. لا تكشفه أبدًا في كود العميل.
• pk_live_… — مفتاح قابل للنشر. محجوز حاليًا؛ لم يُستخدم بعد في أي نقطة وصول.

تنسيق الترويسة

Authorization: Bearer sk_live_5f3a8b2c4d1e9f6a7b8c2d1e9f6a7b8c
Content-Type: application/json
NoKYC-Version: 2026-04-01

استخدم ترويسة NoKYC-Version لتثبيت إصدار محدد من واجهة API (انظر الإصدارات). عند حذفها، يُستخدم الإصدار الافتراضي المثبّت لحسابك.

النطاقات

تُصدر المفاتيح بأحد ثلاثة نطاقات:

يمكن تدوير المفاتيح في أي وقت. تظل المفاتيح القديمة صالحة لمدة 5 دقائق بعد التدوير للسماح بالنشر دون توقف.

الأخطاء

يستخدم API رموز حالة HTTP المعتادة. 2xx تعني النجاح، و4xx تعني وجود مشكلة في طلبك، و5xx تعني أننا ارتكبنا خطأً ونودّ الاطلاع عليه.

غلاف الخطأ

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter `country` is missing.",
    "param": "country",
    "request_id": "req_8a4c2f1e9b3d4a7c"
  }
}

رموز الحالة

أنواع الأخطاء

• invalid_request_error — إدخال مشوّه، أو حقول مفقودة، أو تنسيق غير صالح.
• authentication_error — مشكلة في المفتاح.
• authorization_error — مشكلة في النطاق.
• rate_limit_error — تباطأ في الطلبات.
• api_error — خطأ من جانبنا. قابل لإعادة المحاولة.
• resource_error — حالة المورد تمنع العملية (مثلًا: محاولة إجراء مكالمة من رقم موقوف).
• upstream_error — انتهت مهلة المشغل أو الشريك.

تتضمن كل استجابة خطأ request_id. احرص دائمًا على تسجيله — فهو الطريقة الوحيدة التي يمكن لفريق الدعم من خلالها ربط طلبك بالتتبع الداخلي لدينا.

ترقيم الصفحات

تستخدم نقاط نهاية القوائم ترقيم الصفحات بالمؤشر للأمام فقط. تُعيد ما يصل إلى limit كائنًا (الافتراضي 25، الحد الأقصى 100) وقيمة منطقية has_more. لجلب الصفحة التالية، مرِّر معرّف آخر كائن كـ starting_after.

curl https://api.nokycnumber.com/v1/numbers?limit=10 \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "url": "/v1/numbers",
  "data": [
    { "id": "num_8a4c2f1e9b3d", "object": "number", "number": "+33647189022", … },
    { "id": "num_2k7m9p3w8x4t", "object": "number", "number": "+12025550143", … }
  ],
  "has_more": true,
  "next_cursor": "num_2k7m9p3w8x4t"
}

تُرتَّب القوائم بحيث تظهر الكائنات الأحدث أولًا. ترقيم الصفحات للخلف عبر ending_before غير مدعوم — استخدم المؤشر بدلًا من ذلك.

التكافؤ

تقبل طلبات POST التي تُعدّل الحالة ترويسة Idempotency-Key. نُزيل التكرار استناداً إلى المفتاح لمدة 24 ساعة، مع إعادة الاستجابة المخزّنة مؤقتاً عند إعادة المحاولة. استخدم UUID لكل عملية منطقية.

POST /v1/sms HTTP/1.1
Authorization: Bearer sk_live_…
Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e
Content-Type: application/json

{ "from": "num_8a4c2f1e9b3d", "to": "+33612345678", "body": "Hello" }

إعادة إرسال نفس المفتاح مع محتوى طلب مختلف يُعيد 409 Conflict مع idempotency_key_mismatch.

مفاتيح التكافؤ ليست إلزامية، لكنها موصى بها بشدة لأي عملية تكلّف مالاً (مكالمات، SMS، شراء أرقام). بدونها، قد تؤدي إعادة المحاولة عبر الشبكة إلى مضاعفة الرسوم.

حدود معدل الطلبات

بشكل افتراضي، يقتصر كل مفتاح API على 100 طلب في الدقيقة. يمكن للعملاء ذوي الحجم الكبير طلب رفع الحد من الدعم. تُطبَّق الحدود على كل مفتاح، وليس على كل عنوان IP.

ترويسات الاستجابة

X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 73
X-Rate-Limit-Reset: 1745672460
Retry-After: 8

عند تجاوز الحد المسموح به، ستتلقى 429 Too Many Requests مع ترويسة Retry-After بالثواني. يُنصح بالتراجع التدريجي الخطي لما يصل إلى 4 محاولات إعادة؛ وإن استمرت المشكلة، اطلب رفع الحد.

حصة الاندفاع

يعمل المحدِّد بنظام دلو الرموز — تُتسامح مع الارتفاعات القصيرة التي تتجاوز 100 طلب في الدقيقة طالما ظل المتوسط المتحرك خلال 60 ثانية دون الحد الأقصى.

الإصدارات

إصدارات API مؤرَّخة (2026-04-01). تُشحن التغييرات الجذرية كإصدار مؤرَّخ جديد؛ بينما تُضاف الإضافات غير الجذرية إلى الإصدار الحالي. حدِّد إصداراً باستخدام ترويسة NoKYC-Version.

التوافق

• ندعم كل إصدار لمدة لا تقل عن 24 شهراً بعد الإصدار التالي.
• تُرسَل إشعارات الإيقاف إلى أصحاب الحسابات عبر البريد الإلكتروني قبل 90 يومًا.
• ترويسة الاستجابة NoKYC-Deprecation تنبّهك عند استخدام إصدار قديم.

الإصدار الحالي: 2026-04-01.

الأرقام

الرقم number يمثّل خطًا هاتفيًا افتراضيًا تتحكم فيه. ترتبط الأرقام بدولة ونوع (mobile أو landline) وتحمل فترة فوترة.

curl https://api.nokycnumber.com/v1/numbers?country=fr&type=mobile \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "data": [
    {
      "id": "num_8a4c2f1e9b3d",
      "object": "number",
      "number": "+33647189022",
      "display": "+33 6 47 18 90 22",
      "country": "fr",
      "type": "mobile",
      "tier": "standard",
      "status": "active",
      "billing_period": "yearly",
      "renews_at": "2027-04-26T11:23:00Z",
      "ai_enabled": true,
      "created_at": "2026-04-26T11:23:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl "https://api.nokycnumber.com/v1/numbers/available?country=fr&type=mobile&tier=premium&limit=5" \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "data": [
    { "id": "navail_2k7m9p3w8x4t", "number": "+33611112222", "display": "+33 6 11 11 22 22", "tier": "premium", "pattern": "double-repeat", "price_usd_per_month": 11.98 },
    { "id": "navail_4n2v8j1q6h7y", "number": "+33612345678", "display": "+33 6 12 34 56 78", "tier": "premium", "pattern": "sequential",    "price_usd_per_month": 11.98 }
  ],
  "expires_at": "2026-04-26T11:33:00Z"
}

curl https://api.nokycnumber.com/v1/numbers \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e" \
  -d '{
    "available_id":   "navail_2k7m9p3w8x4t",
    "billing_period": "yearly",
    "addons":         ["ai-pickup"]
  }'

{
  "id": "num_8a4c2f1e9b3d",
  "object": "number",
  "number": "+33611112222",
  "display": "+33 6 11 11 22 22",
  "country": "fr",
  "type": "mobile",
  "tier": "premium",
  "status": "active",
  "billing_period": "yearly",
  "renews_at": "2027-04-26T11:23:00Z",
  "ai_enabled": true,
  "created_at": "2026-04-26T11:23:00Z"
}

curl https://api.nokycnumber.com/v1/numbers/num_8a4c2f1e9b3d \
  -H "Authorization: Bearer sk_live_…"

curl -X DELETE https://api.nokycnumber.com/v1/numbers/num_8a4c2f1e9b3d \
  -H "Authorization: Bearer sk_live_…"

مكالمات

المكالمة call هي جلسة صوتية واحدة تنشأ من أحد أرقامك. تُجرى المكالمات الصادرة عبر POST /v1/calls؛ أما المكالمات الواردة فتُعكس إلى webhook الخاص بك ويمكن استرجاعها أيضًا عبر API.

curl https://api.nokycnumber.com/v1/calls \
  -H "Authorization: Bearer sk_live_…" \
  -d '{
    "from": "num_8a4c2f1e9b3d",
    "to":   "+33612345678",
    "callerid_mask": "rotate"
  }'

{
  "id": "call_2k7m9p3w8x4t",
  "object": "call",
  "from": "num_8a4c2f1e9b3d",
  "from_e164": "+33647189022",
  "to": "+33612345678",
  "status": "ringing",
  "direction": "outbound",
  "started_at": "2026-04-26T11:24:01Z",
  "answered_at": null,
  "ended_at": null,
  "duration_sec": 0,
  "recording_url": null,
  "cost_usd": null
}

رسائل SMS

إرسال واسترجاع SMS. تُقسَّم الرسائل الطويلة تلقائيًا وفق قواعد GSM-03.38 / UCS-2؛ تُظهر الاستجابة عدد الأجزاء الفعلي للفوترة.

curl https://api.nokycnumber.com/v1/sms \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e" \
  -d '{
    "from": "num_8a4c2f1e9b3d",
    "to":   "+33612345678",
    "body": "Bonjour. Your code is 482917."
  }'

{
  "id": "sms_4n2v8j1q6h7y",
  "object": "sms",
  "from_e164": "+33647189022",
  "to": "+33612345678",
  "body": "Bonjour. Your code is 482917.",
  "direction": "outbound",
  "segments": 1,
  "status": "queued",
  "created_at": "2026-04-26T11:24:50Z",
  "delivered_at": null,
  "cost_usd": 0.012
}

رسائل البريد الصوتي

تُخزَّن رسائل البريد الصوتي وتُنسخ وتُترجم تلقائياً. روابط URL للصوت موقّعة مسبقاً وتنتهي صلاحيتها بعد ساعة من الإصدار.

{
  "id": "vm_5p3w8x4t9k2m",
  "object": "voicemail",
  "number_id": "num_8a4c2f1e9b3d",
  "from_e164": "+33612345678",
  "received_at": "2026-04-26T11:25:42Z",
  "duration_sec": 27,
  "audio_url": "https://files.nokycnumber.com/vm/5p3w8x4t9k2m.mp3?expires=1745676342&sig=…",
  "transcript": {
    "text": "Bonjour, c'est Marc. Rappelez-moi quand vous pouvez.",
    "language": "fr",
    "translation_en": "Hello, this is Marc. Call me back when you can.",
    "summary": "Marc asks for a callback.",
    "sentiment": "neutral"
  }
}

إعداد الذكاء الاصطناعي

يمكن لكل رقم تشغيل وكيل ذكاء اصطناعي يرد على المكالمات عند غيابك، ويفلتر المتصلين المجهولين، ويلخّص البريد الصوتي، أو يترجم المحادثات مباشرةً. يمكن الضبط لكل رقم على حدة عبر الموارد الفرعية للذكاء الاصطناعي.

{
  "object": "ai_config",
  "number_id": "num_8a4c2f1e9b3d",
  "addons": ["ai-pickup", "ai-summary"],
  "auto_pickup": {
    "enabled": true,
    "after_rings": 4,
    "script": "I'm unavailable right now. Leave your name, the reason for the call, and a callback number.",
    "language": "auto",
    "voice": "neutral_fr"
  },
  "screening": { "enabled": false },
  "translator": { "enabled": false, "target_language": "en" },
  "voicemail_summary": { "enabled": true, "include_sentiment": true }
}

الأصوات

الأصوات المتاحة: neutral_en، neutral_fr، neutral_es، neutral_de، neutral_jp، warm_en، warm_fr. أصوات مستنسخة مخصصة للمؤسسات عند الطلب.

الحساب

قراءة بيانات الحساب: الرصيد وإحصاءات الاستخدام والـ webhooks المُهيَّأة.

{
  "object": "account",
  "email_hash": "9b3d4a7c8a4c2f1e",
  "balance_usd": 47.32,
  "default_country": "fr",
  "active_numbers": 3,
  "monthly_call_minutes": 412,
  "monthly_sms_segments": 1820,
  "created_at": "2026-04-12T09:15:00Z"
}

Webhooks

اشترك في أحداث حسابك أو أرقام محددة. نُرسل حدث JSON إلى نقطة نهايتك عبر POST ونعيد المحاولة حتى 5 مرات مع تأخير تدريجي أسي على مدى 24 ساعة.

غلاف الحدث

{
  "id": "evt_3d4a7c8a4c2f",
  "object": "event",
  "type": "sms.received",
  "created": "2026-04-26T11:25:42Z",
  "livemode": true,
  "data": { "object": { "id": "sms_…", … } },
  "request_id": "req_8a4c2f1e9b3d4a7c"
}

التحقق من التوقيع

يحمل كل طلب ترويسة X-NoKYC-Signature بالصيغة t=<ts>,v1=<hex>. التوقيع هو HMAC-SHA256 لـ <ts>.<raw_body> باستخدام السر الخاص بنقطة النهاية. ارفض أي طلب يتجاوز عمره 5 دقائق.

# Pseudocode
ts, v1 = parse(header)
if abs(now - ts) > 300: reject
expected = hmac_sha256(secret, f"{ts}.{body}")
if not constant_time_eq(expected, v1): reject

نقاط النهاية

أنواع الأحداث

مخططات الكائنات

number

{
  "id":             "string · num_…",
  "object":         "string · constant \"number\"",
  "number":         "string · E.164",
  "display":        "string · pretty-printed",
  "country":        "string · ISO-2",
  "type":           "enum · mobile | landline",
  "tier":           "enum · standard | premium",
  "tier_pattern":   "string | null · double-repeat | sequential | mirror | round | …",
  "status":         "enum · active | paused | released",
  "billing_period": "enum · monthly | quarterly | yearly",
  "renews_at":      "string · ISO-8601 UTC",
  "auto_renew":     "boolean",
  "addons":         "array · ai-pickup | ai-screen | ai-summary | ai-trans",
  "ai_enabled":     "boolean",
  "metadata":       "object | null",
  "created_at":     "string · ISO-8601 UTC"
}

call

{
  "id":             "string · call_…",
  "object":         "string · constant \"call\"",
  "from":           "string · num_…",
  "from_e164":      "string · E.164",
  "to":             "string · E.164",
  "direction":      "enum · inbound | outbound",
  "status":         "enum · queued | ringing | in_progress | completed | failed | no_answer | busy",
  "started_at":     "string · ISO-8601 UTC",
  "answered_at":    "string | null",
  "ended_at":       "string | null",
  "duration_sec":   "integer",
  "recording_url":  "string | null · pre-signed, expires in 1h",
  "cost_usd":       "number | null"
}

sms

{
  "id":             "string · sms_…",
  "object":         "string · constant \"sms\"",
  "from":           "string · num_…",
  "from_e164":      "string · E.164",
  "to":             "string · E.164",
  "body":           "string",
  "media_urls":     "array · up to 5",
  "direction":      "enum · inbound | outbound",
  "segments":       "integer · 1–10",
  "status":         "enum · queued | sent | delivered | failed | undelivered",
  "failure_code":   "string | null",
  "created_at":     "string · ISO-8601 UTC",
  "delivered_at":   "string | null",
  "cost_usd":       "number | null"
}

SDKs الرسمية

HTTP API هو المرجع الأساسي، غير أن هذه الحزم SDK توفر لك روابط مكتوبة، وإعادة المحاولة، وضمان التوحيد، والتحقق من webhook جاهزةً للاستخدام.

• node npm install @nokycnumber/sdk
• python pip install nokycnumber
• go go get github.com/nokycnumber/sdk-go
• php composer require nokycnumber/sdk
• ruby gem install nokycnumber