API Giriş

MyAIDepartments API, platformun tüm özelliklerine programatik erişim sağlar. RESTful yapıda olan API'miz, modern web standartlarına uygun olarak tasarlanmıştır.

API Temel Bilgiler

Base URL

https://api.myaidepartments.com/v1

Tüm API istekleri bu base URL ile başlamalıdır.

Kimlik Doğrulama

API anahtarı kullanılarak Bearer token authentication yapılır:

Authorization: Bearer YOUR_API_KEY

HTTP Metodları

Response Formatı

Tüm yanıtlar JSON formatındadır:

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-01-10T12:00:00Z",
    "request_id": "req_abc123"
  }
}

Hata Yanıtları

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "API anahtarı geçersiz",
    "details": {}
  }
}

Hızlı Başlangıç

1. API Anahtarı Alın

Dashboard > API Ayarları bölümünden yeni bir API anahtarı oluşturun.

2. İlk İsteğinizi Gönderin

curl https://api.myaidepartments.com/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Yanıtı İnceleyin

{
  "success": true,
  "data": {
    "id": "acc_123456",
    "name": "Şirketiniz",
    "plan": "professional",
    "status": "active"
  }
}

Rate Limiting

API kullanımınız plan tipinize göre sınırlandırılmıştır:

Rate Limit Headers

Her yanıtta aşağıdaki header'lar bulunur:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1673510400

Rate Limit Aşımı

Limiti aştığınızda 429 Too Many Requests hatası alırsınız:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Çok fazla istek gönderdiniz",
    "retry_after": 60
  }
}

SDK ve Kütüphaneler

Resmi SDK'lar

Node.js / TypeScript

npm install @myaidepartments/sdk

import { MyAIDepartments } from "@myaidepartments/sdk";

const client = new MyAIDepartments({
  apiKey: "your_api_key",
});

// Kullanım
const response = await client.conversations.create({
  department: "customer-service",
  message: "Merhaba, yardıma ihtiyacım var",
});

Python

pip install myaidepartments

from myaidepartments import Client

client = Client(api_key='your_api_key')

# Kullanım
response = client.conversations.create(
    department='customer-service',
    message='Merhaba, yardıma ihtiyacım var'
)

PHP

composer require myaidepartments/php-sdk

<?php
use MyAIDepartments\Client;

$client = new Client('your_api_key');

// Kullanım
$response = $client->conversations->create([
    'department' => 'customer-service',
    'message' => 'Merhaba, yardıma ihtiyacım var'
]);

Örnek Kullanım Senaryoları

Senaryo 1: Müşteri Sorgusu Gönderme

const response = await fetch("https://api.myaidepartments.com/v1/analyze", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    department: "customer-service",
    message: "Siparişim ne zaman gelecek?",
    context: {
      customer_id: "cust_123",
      order_id: "order_456",
    },
  }),
});

const data = await response.json();
console.log(data.data.response);

Senaryo 2: Sentiment Analizi

const response = await fetch("https://api.myaidepartments.com/v1/sentiment", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Ürününüz harika, çok memnunum!",
    language: "tr",
  }),
});

// Yanıt: { sentiment: 'positive', score: 0.95 }

Senaryo 3: Lead Kalifikasyonu

const response = await fetch(
  "https://api.myaidepartments.com/v1/leads/qualify",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      lead: {
        name: "Ahmet Yılmaz",
        email: "ahmet@example.com",
        company: "ABC Ltd.",
        message: "Enterprise plan hakkında bilgi almak istiyorum",
      },
    }),
  }
);

// Yanıt: { score: 85, status: 'hot', recommended_action: 'immediate_followup' }

Webhook'lar

API'den gelen olayları gerçek zamanlı almak için webhook'ları kullanabilirsiniz.

Webhook Olayları

• conversation.started - Yeni konuşma başladı
• conversation.completed - Konuşma tamamlandı
• call.incoming - Gelen arama
• call.completed - Arama tamamlandı
• sentiment.detected - Olumsuz sentiment tespit edildi

Webhook Yapılandırması

Dashboard > API > Webhooks bölümünden yapılandırabilirsiniz.

{
  "url": "https://yourapp.com/webhook",
  "events": ["conversation.completed", "call.completed"],
  "secret": "whsec_xxxxxxxxxxxxx"
}

API Versiyonlama

API'miz semantic versioning kullanır. Şu anda aktif versiyon: v1

Version Header

İsteğe bağlı olarak API versiyonunu header ile belirtebilirsiniz:

X-API-Version: 2025-01-01

Sonraki Adımlar

API kullanımı hakkında daha fazla bilgi için:

• 2.1 API Anahtarı Yönetimi - API anahtarlarınızı yönetin
• 2.2 Kimlik Doğrulama - Auth detayları
• 2.3 API Referansı - Tüm endpoint'ler
• 2.4 Webhook'lar - Gerçek zamanlı olaylar