HTTP API v1

مقدمه

API مربوط به NoKYCNumber بر اساس REST سازماندهی شده است. ما از URLهای منبع‌محور قابل پیش‌بینی استفاده می‌کنیم، بدنه‌های JSON-encoded را می‌پذیریم و برمی‌گردانیم، و از کدهای پاسخ 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_… — کلید عمومی. در حال حاضر رزرو شده؛ هنوز توسط هیچ endpoint استفاده نمی‌شود.

فرمت هدر

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

از هدر NoKYC-Version برای تثبیت روی نسخه خاصی از API استفاده کنید (به نسخه‌بندی مراجعه کنید). در صورت حذف، پیش‌فرض تثبیت‌شده حساب شما استفاده می‌شود.

حوزه‌ها

کلیدها با یکی از سه دامنه صادر می‌شوند:

کلیدها می‌توانند در هر زمانی تعویض شوند. کلیدهای قدیمی پس از تعویض به مدت ۵ دقیقه معتبر باقی می‌مانند تا استقرار بدون توقف ممکن باشد.

خطاها

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 را می‌پذیرند. ما به مدت ۲۴ ساعت بر اساس کلید، درخواست‌های تکراری را حذف می‌کنیم و پاسخ کش‌شده را برای تلاش‌های مجدد برمی‌گردانیم. برای هر عملیات منطقی از یک 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 به ۱۰۰ درخواست در دقیقه محدود است. مشتریان با حجم بالا می‌توانند از پشتیبانی درخواست افزایش دهند. محدودیت‌ها بر اساس کلید اعمال می‌شوند، نه بر اساس 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 بر حسب ثانیه دریافت می‌کنید. توصیه می‌شود تا ۴ بار با تأخیر خطی مجدداً تلاش کنید؛ اگر مشکل ادامه داشت، درخواست افزایش محدودیت دهید.

ظرفیت انفجاری

محدودکننده از نوع token bucket است — انفجارهای کوتاه بالای ۱۰۰ درخواست در دقیقه تحمل می‌شوند، مادامی که میانگین متحرک ۶۰ ثانیه‌ای زیر سقف باقی بماند.

نسخه‌بندی

نسخه‌های API دارای تاریخ هستند (2026-04-01). تغییرات شکننده به عنوان نسخه جدید با تاریخ ارائه می‌شوند؛ افزوده‌های غیرشکننده در نسخه فعلی قرار می‌گیرند. نسخه را با هدر NoKYC-Version تثبیت کنید.

سازگاری

• ما از هر نسخه حداقل ۲۴ ماه پس از انتشار نسخه بعدی پشتیبانی می‌کنیم.
• اطلاعیه‌های منسوخ‌سازی ۹۰ روز از پیش به صاحبان حساب ایمیل می‌شود.
• هدر پاسخ NoKYC-Deprecation هنگامی که از نسخه قدیمی استفاده می‌کنید هشدار می‌دهد.

نسخه فعلی: 2026-04-01.

شماره‌ها

یک شماره نمایانگر یک خط تلفن مجازی است که شما کنترل می‌کنید. شماره‌ها به یک کشور و نوع (موبایل یا ثابت) وابسته‌اند و دارای دوره صورت‌حساب هستند.

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_…"

تماس‌ها

یک تماس یک جلسه صوتی منفرد است که از یکی از شماره‌های شما آغاز می‌شود. تماس‌های خروجی از طریق 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"
  }
}

پیکربندی هوش مصنوعی

هر شماره می‌تواند یک عامل هوش مصنوعی اجرا کند که وقتی شما پاسخ نمی‌دهید تماس‌ها را می‌گیرد، تماس‌گیرندگان ناشناس را غربال می‌کند، پست‌های صوتی را خلاصه می‌کند یا مکالمات را به‌صورت زنده ترجمه می‌کند. از طریق زیرمنبع AI به ازای هر شماره پیکربندی کنید.

{
  "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. صداهای کلون‌شده سفارشی برای سازمان‌ها بنا به درخواست.

حساب

خواندن داده‌های سطح حساب: موجودی، آمار مصرف، webhookهای پیکربندی‌شده.

{
  "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 به endpoint شما POST می‌کنیم و تا ۵ بار با تأخیر تدریجی نمایی در طول ۲۴ ساعت تلاش مجدد می‌کنیم.

پوشش رویداد

{
  "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> با استفاده از کلید امضای endpoint است. هر درخواست قدیمی‌تر از ۵ دقیقه را رد کنید.

# 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"
}

SDK های رسمی

HTTP API منبع اصلی است، اما این SDKها به صورت آماده، اتصالات تایپ‌شده، تلاش مجدد، idempotency و تأیید 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