HTTP API v1

Giriş

NoKYCNumber API'si REST etrafında organize edilmiştir. Öngörülebilir kaynak odaklı URL'ler kullanırız, JSON kodlu gövdeleri kabul eder ve döndürürüz, standart HTTP yanıt kodları, kimlik doğrulama ve fiiller kullanırız.

Temel URL

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

Tüm istekler HTTPS üzerinden yapılmalıdır. Düz HTTP üzerinden yapılan istekler 301 Moved Permanently hatasıyla başarısız olur. Kimlik doğrulaması olmayan istekler 401 Unauthenticated hatasıyla başarısız olur.

JSON kuralı

• Gövdesi olan tüm istekler Content-Type: application/json kullanır. Form-encoded gövdeler 415 ile reddedilir.
• Zaman damgaları ISO-8601 UTC dizileri olarak döndürülür (2026-04-26T14:23:00Z) ve aynı formatta kabul edilir.
• Telefon numaraları başında + olan E.164 formatında döndürülür (+33647189022) ve ilgili olduğunda display'de düzgün biçimlendirilir.
• Nesne kimlikleri kaynaklarına göre öneklenir: num_, call_, sms_, vm_, whk_, evt_.

Kimlik doğrulama

Panelinizde Ayarlar → API anahtarları altından verilen bir taşıyıcı anahtarla kimlik doğrulayın. İki anahtar türü mevcuttur:

• sk_live_… — sunucu tarafı gizli anahtarı. Tam okuma/yazma. İstemci kodunda asla açığa çıkarmayın.
• pk_live_… — yayımlanabilir anahtar. Şu anda ayrılmış; henüz hiçbir uç nokta tarafından kullanılmıyor.

Başlık formatı

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

API yüzeyinin belirli bir sürümüne sabitlemek için NoKYC-Version başlığını kullanın (bkz. Sürümleme). Atlandığında, hesabınızın sabitlenmiş varsayılanı kullanılır.

Kapsamlar

Anahtarlar üç kapsam türünden biriyle verilir:

Anahtarlar herhangi bir zamanda döndürülebilir. Eski anahtarlar, kesintisiz dağıtıma izin vermek için rotasyondan sonra 5 dakika daha geçerli kalır.

Hatalar

API geleneksel HTTP durum kodlarını kullanır. 2xx başarı anlamına gelir, 4xx isteğinizle ilgili bir sorun anlamına gelir, 5xx bir hata yaptığımız ve duymak istediğimiz anlamına gelir.

Hata zarfı

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

Durum kodları

Hata türleri

• invalid_request_error — hatalı girdi, eksik alanlar, geçersiz format.
• authentication_error — anahtar sorunu.
• authorization_error — kapsam sorunu.
• rate_limit_error — yavaşlayın.
• api_error — bizim hatamız. Yeniden denenebilir.
• resource_error — kaynak durumu işlemi engelliyor (örn. duraklatılmış bir numaradan arama yapmaya çalışmak).
• upstream_error — operatör veya iş ortağı zaman aşımına uğradı.

Her hata yanıtı bir request_id içerir. Her zaman kaydedin — bu, destek ekibimizin aramanızı dahili izle ilişkilendirebilmesinin tek yoludur.

Sayfalama

Liste uç noktaları yalnızca ileri yönlü imleç sayfalama kullanır. limit'e kadar nesne (varsayılan 25, maks 100) ve bir has_more boolean değeri döndürürler. Sonraki sayfayı almak için son nesnenin kimliğini starting_after olarak gönderin.

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

Listeler en son oluşturulan nesneler başta olacak şekilde sıralanır. ending_before aracılığıyla geriye dönük sayfalama desteklenmez — bunun yerine imleçle ilerleyin.

Idempotency

Durumu değiştiren POST istekleri bir Idempotency-Key başlığı kabul eder. Anahtar için 24 saat boyunca tekilleştirme yaparız ve yeniden denemeler için önbelleğe alınmış yanıtı döndürürüz. Mantıksal işlem başına bir UUID kullanın.

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

Aynı anahtarı farklı gövde içeriğiyle yeniden oynatmak, idempotency_key_mismatch ile 409 Conflict döndürür.

Idempotency anahtarları zorunlu değildir, ancak para gerektiren işlemler (aramalar, SMS, numara satın alımları) için kesinlikle önerilir. Olmadan, ağ yeniden denemesi sizi iki kez ücretlendirebilir.

Hız sınırları

Varsayılan olarak her API anahtarı dakikada 100 istekle sınırlıdır. Yüksek hacimli müşteriler destek ekibinden sınır artışı talep edebilir. Sınırlar anahtar başına uygulanır, IP başına değil.

Yanıt başlıkları

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

Sınırı aştığınızda, saniye cinsinden bir Retry-After başlığıyla 429 Too Many Requests alırsınız. 4 yeniden denemeye kadar doğrusal geri çekilme önerilir; devam ederse, daha yüksek bir sınır talep edin.

Ani yük toleransı

Sınırlayıcı bir token kovasıdır — kayan 60 saniyelik ortalama sınırın altında kaldığı sürece 100 rpm üzerindeki kısa ani artışlar tolere edilir.

Sürümleme

API sürümleri tarihlidir (2026-04-01). Kırıcı değişiklikler yeni tarihli bir sürüm olarak gelir; kırıcı olmayan eklemeler mevcut sürüme eklenir. NoKYC-Version başlığıyla bir sürüme sabitleyin.

Uyumluluk

• Her sürümü bir sonraki sürümden sonra en az 24 ay destekliyoruz.
• Kullanımdan kaldırma bildirimleri, hesap sahiplerine 90 gün önceden e-posta ile gönderilir.
• NoKYC-Deprecation yanıt başlığı, eski bir sürümde olduğunuzda uyarı verir.

Mevcut sürüm: 2026-04-01.

Numaralar

Bir numara, kontrol ettiğiniz sanal bir telefon hattını temsil eder. Numaralar bir ülkeye ve bir türe (mobile veya landline) bağlıdır ve bir faturalama dönemi taşır.

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

Aramalar

Bir arama, numaralarınızdan birinden başlatılan tek bir sesli oturumdur. Giden aramalar POST /v1/calls aracılığıyla yapılır; gelen aramalar webhook'unuza yansıtılır ve API aracılığıyla da alınabilir.

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 mesajları

SMS gönderin ve alın. Uzun mesajlar GSM-03.38 / UCS-2 kurallarına göre otomatik segmentlere bölünür; yanıt, faturalama için gerçek segment sayısını gösterir.

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
}

Sesli mesajlar

Sesli mesajlar otomatik olarak saklanır, yazıya dökülür ve çevrilir. Ses URL'leri ön imzalıdır ve düzenlenmesinden 1 saat sonra sona erer.

{
  "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 yapılandırması

Her numara, siz yanıtlamadığınızda aramaları yanıtlayan, bilinmeyen arayanları filtreleyen, sesli mesajları özetleyen veya konuşmaları canlı olarak çeviren bir AI ajanı çalıştırabilir. AI alt kaynağı aracılığıyla numara bazında yapılandırın.

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

Sesler

Mevcut sesler: neutral_en, neutral_fr, neutral_es, neutral_de, neutral_jp, warm_en, warm_fr. Kurumsal kullanım için talep üzerine özel kopyalanmış sesler.

Hesap

Hesap düzeyindeki verileri okuyun: bakiye, kullanım istatistikleri, yapılandırılmış webhook'lar.

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

Webhook'lar

Hesabınızdan veya belirli numaralardan gelen olaylara abone olun. Uç noktanıza bir JSON olayı POST ederiz ve 24 saat içinde üstel geri çekilmeyle 5 defaya kadar yeniden deneriz.

Olay zarfı

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

İmza doğrulama

Her istek, t=<ts>,v1=<hex> biçiminde bir X-NoKYC-Signature başlığı taşır. İmza, uç noktanın imzalama sırrı kullanılarak <ts>.<raw_body>'nin HMAC-SHA256'sıdır. 5 dakikadan eski olan istekleri reddedin.

# 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

Uç noktalar

Olay türleri

Nesne şemaları

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

Resmi SDK'lar

HTTP API doğruluğun kaynağıdır, ancak bu SDK'lar size kutudan çıkar çıkmaz yazılmış bağlamalar, yeniden denemeler, idempotency ve webhook doğrulaması sağlar.

• 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