Ana sayfaGeliştirici merkeziGeliştirici merkezi

REST API Referansı

Yanıtly REST API endpoint referansı. Authentication, rate limiting ve tüm endpoint detayları.

Yanıtly REST API ile konuşmaları, mesajları, bilgi bankasını ve analitiği programatik olarak yönetin.

Genel Bakış

Base URL

https://api.yanitly.com/v1

Format

JSON (application/json)

Rate Limit

100 req/dakika (Başlangıç), 500 req/dakika (Kurumsal)

Versiyonlama

URL bazlı (/v1/)

Authentication

API isteklerinde JWT Bearer token kullanılır. Token'ı Authorization header'ında gönderin:

Kod örneği
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Kimlik Doğrulama

POST /v1/auth/login

E-posta ve şifre ile giriş yapın. JWT access ve refresh token döner. Hesapta 2FA aktifse, önce requiresTwoFactor: true döner — ardından totpCode ile tekrar istek gönderin.

Request Body

Kod örneği
{
  "email": "user\u0040example.com",
  "password": "your_password",
  "totpCode": "123456"  // 2FA aktifse gerekli (opsiyonel)
}

Response (200)

Kod örneği
// ── Normal Giriş (2FA kapalı) ──
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user\u0040example.com",
    "role": "tenant_admin"
  }
}

// ── 2FA Aktif — İlk Adım (totpCode gönderilmediğinde) ──
{
  "requiresTwoFactor": true,
  "email": "user\u0040example.com"
}
// → Kullanıcıdan 6 haneli TOTP kodunu alıp
//   aynı endpoint'e email + password + totpCode
//   ile tekrar istek gönderin.

POST /v1/auth/refresh

Refresh token ile yeni access token alın.

Request Body

Kod örneği
{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }

POST /v1/auth/register

Yeni kullanıcı ve tenant kaydı oluşturun.

Request Body

Kod örneği
{
  "email": "user\u0040example.com",
  "password": "strong_password",
  "name": "Ahmet Yılmaz",
  "companyName": "Acme Inc."
}

Konuşmalar

GET /v1/conversations

Tenant'a ait konuşma listesini döner. Sayfalama, filtreleme ve sıralama destekler.

Response (200)

Kod örneği
{
  "data": [
    {
      "id": "conv_abc123",
      "channel": "whatsapp",
      "status": "active",
      "lastMessage": "Siparişim nerede?",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 20 }
}

GET /v1/conversations/:id

Belirli bir konuşmanın detaylarını ve mesaj geçmişini döner.

PATCH /v1/conversations/:id

Konuşma durumunu güncelle (active, resolved, archived).

Request Body

Kod örneği
{ "status": "resolved" }

POST /v1/conversations/:id/assign

Konuşmayı bir operatöre ata.

Request Body

Kod örneği
{ "operatorId": "user_uuid" }

Mesajlar

POST /v1/messages

Bir konuşmaya mesaj gönder.

Request Body

Kod örneği
{
  "conversationId": "conv_abc123",
  "content": "Siparişiniz kargoya verildi!",
  "type": "text"
}

GET /v1/conversations/:id/messages

Konuşmadaki mesaj geçmişini getir.

Bilgi Bankası

GET /v1/knowledge

Bilgi bankası içeriklerini listele.

POST /v1/knowledge

Bilgi bankasına yeni içerik ekle.

Request Body

Kod örneği
{
  "title": "İade Politikası",
  "content": "Ürünler 14 gün içinde...",
  "category": "Politikalar"
}

DELETE /v1/knowledge/:id

Bilgi bankasından içerik sil.

Kanallar

GET /v1/channels

Bağlı kanalları listele.

POST /v1/channels

Yeni kanal bağlantısı oluştur ve kanal yapılandırmasını kaydet.

Analitik

GET /v1/analytics/overview

Genel analitik verilerini getir (konuşma sayısı, ortalama yanıt süresi, memnuniyet puanı).

Response (200)

Kod örneği
{
  "totalConversations": 1250,
  "avgResponseTime": 12.5,
  "satisfactionScore": 4.6,
  "aiResolutionRate": 78.3,
  "period": "last_30_days"
}

GET /v1/analytics/conversations

Konuşma analitiklerini getir (tarih bazlı dağılım).

Webhooks

GET /v1/webhooks

Kayıtlı webhook'ları listele.

POST /v1/webhooks

Yeni webhook kaydı oluştur.

Request Body

Kod örneği
{
  "url": "https://yourapp.com/webhooks/yanitly",
  "events": ["conversation.created", "message.received"],
  "secret": "your_webhook_secret"
}

Hata Kodları

400 Bad Request — İstek formatı hatalı

401 Unauthorized — Geçersiz veya eksik token

403 Forbidden — Bu işlem için yetkiniz yok

404 Not Found — Kaynak bulunamadı

409 Conflict — Kaynak zaten mevcut

429 Too Many Requests — Rate limit aşıldı

500 Internal Server Error — Sunucu hatası

İlgili Kaynaklar