Ana içeriğe geç

Sıkça Sorulan Sorular

Başlangıç​

API'yi kullanmaya nasıl başlarım?

KolayBi API'yi kullanmaya başlamak için:

  1. KolayBi hesabınızdan API anahtarınızı alın.
  2. Channel bilginizi KolayBi destek ekibinden (api.support@kolaybi.com) talep edin.
  3. Access token oluşturun.
  4. İlk API çağrınızı yapın.

Detaylı adım adım talimatlar için Başlarken Kılavuzu sayfasını inceleyin.

Test ortamı var mı?

Evet, geliştirme ve test amaçlı sandbox ortamımız mevcuttur:

  • Sandbox API URL: https://ofis-sandbox-api.kolaybi.com/kolaybi/v1
  • Sandbox Web Arayüzü: https://ofis-sandbox.kolaybi.com
  • Production API URL: https://ofis-api.kolaybi.com/kolaybi/v1

Production'a geçmeden önce tüm işlemlerinizi sandbox ortamında test etmenizi öneriyoruz.

Hangi programlama dillerinde kod örnekleri mevcut?

Dokümantasyonumuzda aşağıdaki dillerde kod örnekleri bulabilirsiniz:

  • JavaScript/Node.js
  • PHP
  • Python
  • C#
  • cURL

Detaylı örnekler için Kod Örnekleri bölümünü ziyaret edin.

Kimlik Doğrulama​

Access token nasıl alırım ve ne kadar süre geçerli?

Access token almak için API anahtarınızı ve Channel bilginizi kullanın:

curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/access_token" \
  -H "Channel: YOUR_CHANNEL" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

Geçerlilik süresi: Access token'lar 24 saat geçerlidir. Süre dolduğunda yeni token almanız gerekir.

401 Unauthorized hatası alıyorum, ne yapmalıyım?

401 hatası kimlik doğrulama sorununu gösterir. Olası nedenler ve çözümler:

Nedenler:

  • Token süresi dolmuş (24 saat)
  • Yanlış token formatı
  • API anahtarı değiştirilmiş veya iptal edilmiş
  • Eksik Authorization header

Çözüm:

  1. Yeni access token alın
  2. Authorization header formatını kontrol edin: Bearer YOUR_ACCESS_TOKEN
  3. Channel header'ının doğru olduğundan emin olun
Channel bilgisini nereden alırım?

Channel bilginiz entegrasyonunuzu tanımlayan özel bir değerdir. Tüm API isteklerinde zorunludur.

KolayBi API destek ekibinden (api.support@kolaybi.com) talep edebilirsiniz.

Channel bilgisi tüm isteklerde header olarak gönderilmelidir:

-H "Channel: YOUR_CHANNEL"

Faturalar​

E-fatura nasıl gönderilir?

E-fatura gönderme işlemi 3 adımda gerçekleşir:

  1. Fatura oluştur: POST /invoices endpoint'ini kullanarak faturayı oluşturun
  2. Resmileştir: POST /e-document endpoint'ini kullanarak e-document ile resmileştirin
  3. Durum kontrol: GET /invoices/{id} ile gönderim durumunu kontrol edin

Detaylı bilgi ve kod örnekleri için E-Fatura Dokümantasyonu sayfasını inceleyin.

Farklı fatura türlerini nasıl iptal edebilirim?

İptal işlemi fatura durumuna göre değişir:

  • Resmileşmemiş faturalar: DELETE endpoint'i ile tamamen silebilirsiniz.
  • E-arşiv faturalar: İptal işlemi yapabilirsiniz.
  • E-faturalar: İptal edilemez, bunun yerine iade faturası kesmeniz gerekir.

İptal işlemleri için uygun endpoint'leri kullanın ve fatura durumunu kontrol edin.

Toplu fatura işlemleri nasıl yapılır?

Toplu fatura oluşturmak için döngü kullanabilirsiniz, ancak rate limiting kurallarına dikkat edin:

for (const invoice of invoices) {
  await createInvoice(invoice);
  // Rate limiting için bekleme süresi
  await new Promise((resolve) => setTimeout(resolve, 100));
}

Rate Limiting Kuralları:

  • Fatura oluşturma: 100 istek/saat
  • E-fatura gönderimi: 50 istek/saat
  • Genel API: 1000 istek/saat

Hata Çözümleri​

400 Bad Request hatası neden alıyorum?

400 hatası geçersiz istek parametreleri anlamına gelir. Yaygın nedenler:

  • Eksik zorunlu parametreler
  • Yanlış parametre formatı
  • Geçersiz değerler

Çözüm: İstek parametrelerinizi ve formatlarını kontrol edin. Hata mesajında hangi alanın sorunlu olduğu belirtilir.

403 Forbidden hatası ne anlama gelir?

403 hatası yetki eksikliğini gösterir:

Olası nedenler:

  • API anahtarınızın gerekli izinleri yok
  • Yanlış Channel header
  • IP adresi kısıtlaması

Çözüm: API anahtarınızın izinlerini kontrol edin ve Channel header'ını doğrulayın.

429 Rate Limit hatası nasıl çözülür?

429 hatası istek limitini aştığınızı gösterir:

Çözüm:

  1. İstek sıklığınızı azaltın.
  2. Response header'ındaki retry_after değeri kadar bekleyin.

Rate Limitler:

  • Genel: 1000 istek/saat
  • Fatura oluşturma: 100 istek/saat
  • E-fatura gönderimi: 50 istek/saat
500 Internal Server Error nasıl ele alınır?

500 hatası sunucu kaynaklı geçici bir sorundur:

Çözüm:

  1. Birkaç dakika bekleyin
  2. İsteği tekrarlayın
  3. Sorun devam ederse api.support@kolaybi.com ile iletişime geçin

Bu hata genellikle geçicidir ve sistem tarafındaki sorunlardan kaynaklanır.

Müşteri Yönetimi (Cari Hesap)​

Yeni müşteri nasıl oluşturulur?

Yeni müşteri oluşturmak için associates endpoint'ini kullanın:

curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Ahmet&surname=Yılmaz&identity_no=12345678901"

Zorunlu alanlar:

  • name: İsim (minimum 2 karakter)
  • surname: Soyisim (minimum 2 karakter)
  • identity_no: TCKN (11 haneli) veya VKN (10 haneli)
Müşteri bilgilerini güncelleyebilir miyim?

Şu anda API üzerinden müşteri bilgisi güncelleme desteklenmemektedir.

Müşteri bilgilerini güncellemek için KolayBi web arayüzünü kullanmanız gerekiyor.

Toplu müşteri ekleme nasıl yapılır?

Toplu müşteri eklemek için döngü kullanabilirsiniz:

for (const customer of customers) {
  await createAssociate(customer);
  // Rate limiting için bekleme
  await new Promise((resolve) => setTimeout(resolve, 100));
}

Önemli: Rate limiting kurallarına uygun şekilde istekler arasında bekleme süresi ekleyin.

Müşteri ödemesi nasıl işlenir?

Müşteri ödemelerini transactions proceed endpoint'i ile işleyebilirsiniz:

curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates/{id}/transactions/proceed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -d "amount=1000&description=Ödeme açıklaması"

Ürün Yönetimi​

Ürün stoğunu nasıl güncellerim?

Stok güncellemesi stok hareketi endpoint'i ile yapılır:

POST /products/{id}/stock

Parametreler:

  • stock_flow_direction: 1 → Stok girişi (artırma)
  • stock_flow_direction: -1 → Stok çıkışı (azaltma)
  • quantity: Hareket miktarı
  • description: Hareket açıklaması

Detaylı bilgi için Stok Hareketi dokümantasyonunu inceleyin.

Ürün fiyatını nasıl güncellerim?

Ürün fiyatını güncellemek için PUT endpoint'ini kullanın:

curl -X PUT "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/products/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -d "sale_price=150.00&purchase_price=100.00"
Barkod ile ürün arama nasıl yapılır?

Barkod ile ürün aramak için products endpoint'inde barcode parametresini kullanın:

GET /products?barcode=1234567890123

Barkod araması tek ürün döndürür ve tam eşleşme gerektirir.

Teknik Detaylar​

API rate limit kuralları nelerdir?

KolayBi API'de farklı endpoint'ler için ayrı rate limit'ler uygulanır:

  • Genel API: 1000 istek/saat
  • Fatura oluşturma: 100 istek/saat
  • E-fatura gönderimi: 50 istek/saat

Rate limit aşıldığında:

  • 429 Too Many Requests hatası alırsınız.
  • Response header'ında retry_after değeri belirtilir.
  • Bu süre kadar bekleyip tekrar denemelisiniz.
Güvenlik gereksinimleri nelerdir?

HTTPS Zorunluluğu: Tüm API istekleri HTTPS üzerinden yapılmalıdır. HTTP istekleri kabul edilmez.

Kimlik Doğrulama: Her istekte geçerli access token ve Channel header gereklidir.

IP Kısıtlamaları: Canlı ortamda API anahtarınız için IP kısıtlaması talep edilebilir.

API versiyonlama nasıl çalışır?

Şu anda API v1 versiyonu aktiftir ve URL'de belirtilir:

https://ofis-api.kolaybi.com/kolaybi/v1/

Yeni versiyonlar geriye uyumlu şekilde geliştirilir ve önceden duyurulur.

Destek ve İletişim​

Teknik destek nasıl alabilirim?

Destek Kanalları:

Yanıt Süreleri:

  • Kritik sorunlar: 2 saat içinde
  • Normal sorunlar: 24 saat içinde
  • Genel sorular: 48 saat içinde
Hata raporu nasıl iletirim?

Etkili hata raporu için aşağıdaki bilgileri paylaşın:

Zorunlu Bilgiler:

  • Endpoint URL'si
  • HTTP method (GET, POST, etc.)
  • İstek parametreleri ve header'ları
  • Aldığınız tam hata mesajı
  • Hata zamanı (timestamp)

Ek Yararlı Bilgiler:

  • Kullandığınız programlama dili
  • Beklediğiniz sonuç
  • Sorunu yeniden oluşturma adımları
Yeni özellik talebi nasıl yaparım?

Özellik taleplerini api.support@kolaybi.com adresine gönderin.

Talebinizde belirtin:

  • Özelliğin detaylı açıklaması
  • İş ihtiyacı ve kullanım senaryosu
  • Mevcut çözümünüzün eksiklikleri
  • Önerilen implementasyon (varsa)
  • Öncelik seviyesi ve timeline

Talepler değerlendirilerek geliştirme roadmap'ine alınır.