API anahtarları ve kapsamlar

Ringhum REST API'si, kendi sistemlerinizin çalışma alanınızla etkileşime girmesini sağlar: aramaları ve dökümleri listeleyin, asistan oluşturun, randevu alın, kişileri yönetin, giden arama yapın ve daha fazlası. Her istek, tek bir çalışma alanına ait bir API anahtarı ile doğrulanır. Bu makale, anahtar oluşturmayı ve her uç noktanın paylaştığı ortak kuralları anlatır. Uç noktaların tam referansı /docs adresindedir.

Anahtarları kim yönetebilir

API, her planda kullanılabilir. Bir anahtarın yapabilecekleri yine de planınızla sınırlıdır: örneğin plan sınırınızın üzerinde bir asistan oluşturmak hata döndürür.

API anahtarı oluşturma

1. Kenar çubuğundan Geliştiriciler'i açın.
2. API anahtarları kartında Anahtar oluştur'a tıklayın.
3. Anahtarın nerede kullanıldığını belirten bir Anahtar adı girin, örneğin "Üretim sunucusu".
4. Kapsamlar altında read, write veya her ikisini işaretleyin.
5. Anahtar oluştur'a tıklayın.
6. Anahtarı yeşil kutudan kopyalayın ve sunucunuzun gizli bilgi deposu gibi güvenli bir yerde saklayın. Bitti'ye tıklayın.

Önemli: Anahtar yalnızca bir kez gösterilir. Ringhum yalnızca onun bir parmak izini saklar, bu yüzden tekrar gösterilemez. Anahtarınızı kaybederseniz yeni bir anahtar oluşturun ve eskisini iptal edin.

Anahtarlar ck_live_ ile başlar. API anahtarları tablosu her anahtarın adını, anahtarın ilk karakterlerini, kapsamlarını, en son ne zaman kullanıldığını ve Aktif mi yoksa İptal edildi mi olduğunu gösterir.

Kapsamlar

Her anahtar yalnızca okuma yapan uç noktaları çağırabilir. Bir şey oluşturan, değiştiren veya silen uç noktalar write kapsamını gerektirir. Örnekler: arama yapmak, mesaj göndermek, randevu almak veya bir asistanı güncellemek. /docs adresindeki referans bu uç noktaları işaretler. write kapsamı olmayan bir anahtar bunlarda 403 hatası alır.

Her sisteme ihtiyaç duyduğu en küçük erişimi verin. Bir raporlama panosunun yalnızca read'e ihtiyacı vardır.

Anahtar iptal etme

1. Geliştiriciler'de, anahtarı API anahtarları tablosunda bulun.
2. İptal et'e tıklayın ve onaylayın.

Anahtarı kullanan istekler hemen 401 hatasıyla başarısız olur. İptal edilen anahtarlar, geçmişlerini görebilmeniz için İptal edildi işaretiyle listede kalır. Bir anahtar düzenlenemez: kapsamlarını değiştirmek için yeni bir anahtar oluşturun ve eskisini iptal edin.

İstek gönderme

• Temel URL: https://ringhum.com/api/v1
• Kimlik doğrulama: anahtarı Bearer belirteci olarak gönderin: Authorization: Bearer ck_live_…
• Biçim: giriş ve çıkışta JSON. Bir gövdeyle birlikte Content-Type: application/json gönderin.
• Zamanlar UTC cinsinden ISO 8601 biçimindedir. Telefon numaraları E.164 biçimindedir, örneğin +14155550132. Kimlikler tam sayıdır.
• Güncellemeler yalnızca değiştirmek istediğiniz alanlarla PATCH kullanır.
• Her yanıt bir X-Request-Id başlığı taşır. Destekle iletişime geçtiğinizde bunu ekleyin.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Bir anahtarın hangi çalışma alanına ait olduğunu kontrol etmek için GET /me çağrısı yapın.

Yanıtlar ve sayfalama

Tek bir nesne {"data": {…}} olarak döner. Sayfalanmış listeler bir meta nesnesiyle döner:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Sonuçlar arasında gezinmek için page ve per_page kullanın. per_page varsayılan olarak 25'tir ve en fazla 100 olabilir.

Hatalar

Her hata aynı yapıya sahiptir ve kodunuzda kontrol edebileceğiniz sabit bir type içerir:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Hız sınırları

Dakikada 120 istek yapabilirsiniz. Yanıtlar X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını içerir. Sınırı aştığınızda, beklenecek saniyeyi veren bir Retry-After başlığıyla 429 alırsınız.

İpucu: Arama sonuçlarını yoklamayın (polling). call.ended için bir webhook ekleyin, Ringhum arama bittiğinde özeti ve dökümü size gönderir. Bkz. Webhooks.

Sık sorulan sorular

Makine tarafından okunabilir bir şema var mı? Evet. OpenAPI 3.1 tanımı /api/v1/openapi.json adresindedir ve anahtar gerektirmez. Ondan bir istemci üretebilirsiniz.

Anahtarı oluşturan kişi ayrılırsa anahtar çalışmayı durdurur mu? Hayır. Anahtarlar çalışma alanına aittir ve iptal edilene kadar çalışmaya devam eder. Artık güvenmediğiniz anahtarları, özellikle erişimi olan biri ayrıldığında iptal edin.

API'yi bir web sayfasından kullanabilir miyim? Hayır. Sayfayı açan herkes anahtarı okuyabilir. API'yi sunucunuzdan çağırın.