Müşteri · Ayarlar

Entegrasyon API'si

Kendi yazılımınızdan fiyat alma, sipariş açma ve durumu izleme; API dokümanı, ilk istekler, toplu sipariş, tekrar deneme, webhook imzası ve sınırlar.

Entegrasyon API'si, sipariş, ERP ya da depo yazılımınızın Courino'ya doğrudan bağlanmasını sağlar. Portalda elle yaptığınız sipariş işlerinin hepsini yazılımınız da yapabilir: fiyat alır, sipariş açar, düzenler, iptal eder, durumu ve canlı konumu izler. Bu yazı yazılım geliştiriciniz için bir başlangıç rehberidir.

Fiyat, kurye firmanızın size tanımladığı fiyat listesinden portaldakiyle aynı hesapla çıkar. API ile açılan sipariş, firmanın ekranına elle girilmiş sipariş gibi düşer.

Neye ihtiyacınız var?

Hesabınızda API ve webhook izni. Yoksa kurye firmanızdan isteyin.
Bir API anahtarı. Nasıl oluşturulacağı API anahtarı oluşturma yazısında.
Siparişlerin durumunu sisteminize otomatik almak istiyorsanız bir webhook aboneliği: Webhook ekleme.

İlk sipariş adım adım

Bilgilerim sayfasındaki Entegrasyon (API anahtarları) kartında anahtar oluşturun.
Aynı kartın sağ üstündeki API dokümanı düğmesine basın. Doküman yeni sekmede, portalı hangi dilde kullanıyorsanız o dilde (Türkçe ya da İngilizce) açılır.
Dokümanda Authorize'a basın, anahtarı yapıştırıp onaylayın. Artık her ucu Try it out ile tarayıcıdan, gerçek hesabınızla deneyebilirsiniz.
GET /me/order-options ile semtleri ve gidiş tiplerini alın. Siparişteki her adreste semt kimliği (districtId) ve bir gidiş tipi (deliveryTypeId) gerekir.
POST /pricing/quote ile fiyatı görün. Bu istek hiçbir şey kaydetmez.
POST /orders ile siparişi açın. Yanıtta siparişin kimliği (id) ve numarası (number) döner.
Durumu GET /me/orders/{id} ile okuyun ya da webhook ile dinleyin.

Gönderen her zaman anahtarın bağlı olduğu müşteri hesabıdır. İstekte gönderen bilgisini boş ({}) bırakabilirsiniz.

Sık kullanılan uçlar

Adreslerin hepsi /api/v1 altındadır (ör. https://client.courino.com/api/v1/orders).

Uç	Ne yapar
`GET /me/order-options`	Semtler, gidiş tipleri ve çalışma saatleri
`POST /pricing/quote`	Fiyat teklifi (kaydetmez)
`POST /orders`	Sipariş açar
`POST /me/orders/batch`	Toplu sipariş (en çok 1000 satır)
`GET /me/orders`	Siparişlerim; referans no, barkod, durum ve tarihle süzme, `q` ile metin araması, `minAmount`/`maxAmount` ile tutar aralığı, `sort` ile sıralama (ör. `sort=-total`)
`GET /me/orders/{id}`	Sipariş ayrıntısı
`PUT /me/orders/{id}`	Henüz havuzdaki siparişi düzenler
`POST /me/orders/{id}/cancel`	Siparişi iptal eder
`GET /me/orders/{id}/tracking`	Kurye yoldayken canlı konum
`POST /me/orders/{id}/tracking-link`	Alıcıya iletilecek takip bağlantısı
`POST /me/orders/imports`	Excel/CSV gönderi dosyasını önizler; `.../confirm` ile siparişler açılır
`GET /me/ecommerce/orders`	Bağlı mağazalarınızdan gelen siparişler; eşleşme bekleyeni düzeltme, yeniden deneme, atlama
`GET /me/customer/statement`	Dönem hesap ekstresi (PDF)
`GET /me/customer/payments`	Online ödemeleriniz (yalnız okuma)
`GET /me/customer/messages`	Size ve yetkililerinize gönderilen SMS ve e-postalar

Bu tablo yalnız sık kullanılanlardır; ödeme ve fatura, kapıda ödeme, yetkililer ve özel günler uçlarının tamamı dokümanda.

Güvenle tekrar deneme

Ağ koptuğunda isteğin ulaşıp ulaşmadığını bilemezsiniz. Sipariş açarken ve iptal ederken Idempotency-Key başlığına o işe özgü bir değer (ör. kendi sipariş numaranız) yazın. Aynı değerle tekrar gönderdiğinizde ikinci sipariş açılmaz, ilk yanıt döner. Aynı değerle farklı içerik gönderirseniz 409 hatası alırsınız. Değer 24 saat saklanır.

Toplu siparişte her satırın referans no'su (reference) aynı işi görür: aynı referanslı sipariş ikinci kez açılmaz. Toplu isteği önce dryRun: true ile gönderip yalnız denetleyebilirsiniz. Ayrıntılar Toplu gönderi yazısında.

Webhook imzasını doğrulama

Her webhook isteğinde şu başlıklar gelir:

X-KOS-Event: olayın adı (ör. order.delivered).
X-KOS-Delivery: haberin kimliği; yeniden denemelerde değişmez. Saklayın ve tekrarı atlayın.
X-KOS-Signature: t=1761040000,v1=9f2c… biçiminde imza (t gönderim zamanı, v1 imza).

İmzayı doğrulamak için t değerini, bir nokta ve isteğin ham gövdesini yan yana koyup imza sırrıyla (whsec_ dahil tamamı) HMAC-SHA256 hesaplayın; sonucu v1 ile karşılaştırın. Zamanı 5 dakikadan eski istekleri reddedin. Yanıt olarak hızlıca 2xx dönün; 410 dönerseniz o haber için deneme durur. Kod örneği dokümanda ve courino.com/gelistiriciler sayfasında.

Kurallar ve sınırlar

Bir anahtarla dakikada en çok 120 istek. Aşılırsa 429 döner; yanıttaki Retry-After kadar bekleyin. Her yanıtta kalan hakkınız X-RateLimit-Remaining başlığında yazar.
Hesap başına en çok 5 etkin anahtar ve 5 webhook aboneliği.
Tutarlar metin olarak döner (ör. "185.00"); kuruş kaybını önlemek için sayıya çevirirken dikkatli olun.
Hatalar application/problem+json biçimindedir; code alanı hatanın makine tarafından okunacak adıdır, alan hatalarında hangi alanın yanlış olduğu yazar.
Telefonu istediğiniz biçimde gönderebilirsiniz (ör. 0532 123 45 67); yanıtta +905321234567 biçiminde döner.

Sorun mu var?

401 hatası alıyorum: Anahtar yanlış, iptal edilmiş ya da şifre değişikliği yüzünden kapanmış olabilir. Portalda anahtarın durumuna bakın, gerekirse yeni anahtar oluşturun.
403 hatası alıyorum: Anahtarı oluşturan hesabın o iş için izni yoktur (ör. sipariş verme izni); kurye firmanızdan izni isteyin. Kayıtlı kartlar, destek talepleri ve ödeme başlatma gibi oturum isteyen işler anahtarla hiç yapılamaz; bunları portaldan yapın.
"Semt bulunamadı" ya da gidiş tipi hatası: Kimlikleri GET /me/order-options yanıtından alın; adla gönderemezsiniz.
Doküman açılmıyor: API dokümanı düğmesini müşteri portalının içinden kullanın; doküman portalla aynı adrestedir.
Takılırsanız: Hata yanıtının tamamını ve istek zamanını destek@courino.com adresine gönderin.