Söyle Gelir Geliştiriciler

Kimlik doğrulama ve kurallar

Adresler

API Taban adres Kim kullanır
İşletme ve POS API https://soylegelir.com/api/v1/merchant İşletmenin kendi yazılımı, bağlı POS firması
Kurye API https://soylegelir.com/api/v1/courier Bağlı kurye firması

Bütün istekler HTTPS ile yapılır; gövdeli isteklerde Content-Type: application/json gönderin.

İşletme anahtarı

İşletmenin kendi yazılımı için. İşletme panelinde Ayarlar › API ve entegrasyon › API anahtarı oluştur ile alınır; yalnız oluşturulduğu anda bir kez gösterilir. Her istekte gönderilir:

Authorization: Bearer sg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Anahtar tek bir işletmeye bağlıdır; bütün uçlar yalnız o işletmenin sipariş ve ürünlerini görür.
  • Yenilenince eski anahtar hemen geçersiz olur.

Firma anahtarları (POS ve kurye firmaları)

İşletme panelinden firmanızı seçtiğinde iki anahtar oluşur; ikisi her istekte birlikte gönderilir:

X-Api-Key: sgk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Secret: sgs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • API anahtarı bağlantının (işletme + firma) kimliğidir; hangi işletmenin isteği olduğu buradan anlaşılır.
  • Gizli anahtar isteği doğrular ve size gelen webhook'ların imzasını doğrulamak için kullanılır. Yalnız sunucunuzda saklayın; tarayıcıya, mobil uygulamaya ya da sürüm kontrolüne koymayın.
  • Firma birden çok işletmeyle çalışıyorsa her işletme için ayrı bir anahtar çifti vardır.
  • POS firmaları işletme API'sini, kurye firmaları kurye API'sini kullanır; anahtar yanlış API'de 403 alır.

Kimlik hataları

Durum Yanıt Ne zaman
401 {"message": "Geçersiz API anahtarı."} Anahtar yok, biçimi yanlış, tanınmıyor ya da gizli anahtar tutmuyor
403 {"message": "İşletme hesabı askıda."} İşletme anahtarı: işletme yayında değil ya da hesabı kapalı
403 {"message": "Bu anahtar bu API için değil."} Firma anahtarı yanlış API'de (POS anahtarı kurye API'sinde ya da tersi)
403 {"message": "Entegrasyon bağlantısı askıda."} Firma pasif, işletme yayında değil ya da işletme sahibinin hesabı kapalı

Ortak başlıklar

Başlık Zorunlu Açıklama
Authorization ya da X-Api-Key + X-Api-Secret Evet Kimlik doğrulama
Content-Type: application/json Gövdeli isteklerde İstek gövdesi JSON
Accept: application/json Önerilir Hatalar bu başlık olmasa da JSON döner
Accept-Language Hayır tr ya da en: genel hata metinleri (404, 405, 429, 500) o dilde döner

Hız sınırları

API Sınır Sayaç
İşletme ve POS API Dakikada 120 istek İşletme başına (işletmenin anahtarı ve bağlı POS firması ortak)
Kurye API Dakikada 240 istek Bağlantı (işletme + firma) başına
Geçersiz anahtarla gelen istekler Dakikada 10 istek IP adresi başına
  • Yanıtlarda X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları bulunur.
  • Sınır aşılınca 429 döner; Retry-After başlığındaki saniye kadar bekleyip yeniden deneyin.
  • Siparişleri sık sorgulamak yerine webhook kullanın; düzenli çekimde since parametresiyle yalnız değişenleri isteyin.

Hata biçimi

Bütün hatalar JSON'dur: {"message": "<metin>"}. Doğrulama ve iş kuralı hataları ek olarak alan adına göre gruplanmış errors taşır:

{
  "message": "Lütfen bir gerekçe yazın.",
  "errors": { "note": ["Lütfen bir gerekçe yazın."] }
}
Durum Anlamı
200 Başarılı
401 / 403 Kimlik hatası (yukarıda)
404 Kayıt yok ya da bu anahtarın göremeyeceği bir kayıt (başka işletmenin siparişi vb.)
405 Adres var ama yöntem desteklenmiyor
409 Çakışma: sipariş bu arada başka bir taşıyıcıya geçti
422 Doğrulama hatası ya da siparişin şu anki durumunda yapılamayan işlem
429 Hız sınırı aşıldı
500 Beklenmeyen hata (iç ayrıntı dönmez); kısa süre sonra yeniden deneyin

Yazılımınız metne değil durum koduna ve errors anahtarlarına bakmalıdır; hata metinleri değişebilir.

Biçimler

  • Tutarlar kuruş cinsinden tam sayıdır: 235,00 TL = 23500. Sipariş nesnesi currency: "TRY" ve amounts_in: "kurus" alanlarını taşır.
  • Tarihler ISO 8601 biçimindedir: 2026-11-14T12:05:00+00:00.
  • Konumlar ondalık derecedir (lat -90…90, lng -180…180).
  • Sipariş numarası (number, ör. SG261114GCCE) siparişin dışa açık kimliğidir; uçlarda bununla çalışılır.

Sürümleme

Adresteki v1 API sürümüdür. v1 içinde yanıtlara yeni alanlar eklenebilir, yeni uçlar ve olaylar gelebilir; mevcut alanların adı ve türü değişmez. Yazılımınız tanımadığı alanları yok saymalıdır. Değişiklikler sürüm notlarında duyurulur.