EN Müşteri girişi Firma girişi
Geliştiriciler · Entegrasyon API'si

Kendi yazılımınızdan kurye çağırın.

Sipariş, ERP ya da depo sisteminiz Courino'ya doğrudan bağlansın: fiyatı alın, siparişi açın, teslim edilince imzalı webhook ile haber alın. Kurye firmanızın panelinde sipariş elle girilmiş gibi görünür.

API dokümanını açın OpenAPI dosyası (YAML)

Dokümanın İngilizcesi: API docs (English)

REST + JSONOpenAPI 3Swagger'da canlı denemeHMAC imzalı webhookIdempotency-Key
Neler hazır?

Bir kurye entegrasyonunda ihtiyacınız olan her şey

Portalda elle yaptığınız her sipariş işini API'den de yapabilirsiniz. Fiyat, kurye firmanızın size tanımladığı fiyat listesiyle aynı hesapla çıkar.

REST + OpenAPI 3

JSON gövde, açık hata kodları (application/problem+json). OpenAPI dosyasını indirip istemci kodunu kendi dilinizde üretebilirsiniz.

Swagger'da canlı deneme

Dokümanda Authorize'a anahtarınızı yapıştırın, her ucu tarayıcıdan gerçek hesabınızla deneyin. Türkçe ve İngilizce.

İmzalı webhook

Alındı, teslim edildi, iptal… her olay X-KOS-Signature (HMAC-SHA256) ile imzalı gelir. Ulaşamazsa yeniden denenir; X-KOS-Delivery denemelerde aynı kalır.

Güvenle tekrar deneme

Sipariş açarken ve iptal ederken Idempotency-Key gönderin: ağ koptu diye aynı istek iki sipariş açmaz, ilk yanıt döner.

Toplu sipariş

Tek istekte 1000 satıra kadar gönderi. Önce yalnız denetleyin (dryRun), sonra açın; aynı referans no ikinci kez sipariş olmaz.

Canlı takip bağlantısı

Siparişin takip bağlantısını alın, alıcınıza kendi kanalınızdan iletin. Kurye yoldayken konumu siz de API'den okuyabilirsiniz.

Hazır e-ticaret bağlantıları

Trendyol, Hepsiburada, Shopify, WooCommerce ve diğerleri için kod yazmanız gerekmez; portaldaki E-ticaret mağazam'dan bağlanır.

Ayrı ve iptal edilebilir anahtarlar

Her sistem için ayrı anahtar (en çok 5), son kullanım zamanı görünür. Anahtar şifre, kart ve hesap ayarlarına dokunamaz.

Kod örneği

Fiyat alın, siparişi açın, olayı doğrulayın

Örneklerdeki <semt-id> ve <gidiş-tipi-id> değerlerini GET /me/order-options yanıtından alırsınız. Tutarlar her yerde metin olarak ("185.00") döner; kuruş kaybı olmaz.

bash
# Fiyat teklifi: kaydetmez, yalnız hesaplar
curl https://client.courino.com/api/v1/pricing/quote \
  -H "Authorization: Bearer $COURINO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer": "sender",
    "sender": {},
    "recipient": { "districtId": "<semt-id>" },
    "deliveryTypeId": "<gidiş-tipi-id>"
  }'

Ne döner?

  • total: KDV dahil toplam, lines: kırılım (taban, ekstra, bekleme, KDV…).
  • Gönderen her zaman anahtarın bağlı olduğu müşteri hesabıdır; sender boş bırakılabilir.
  • Siparişte aynı hesap yeniden yapılır; teklif ile sipariş tutarı aynı kuralla çıkar.
bash
# Sipariş aç: ağ hatasında aynı Idempotency-Key ile tekrarlayın
curl https://client.courino.com/api/v1/orders \
  -H "Authorization: Bearer $COURINO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: SIP-48213" \
  -d '{
    "payer": "sender",
    "sender": {},
    "recipient": {
      "name": "Ayşe Demir",
      "phone": "0532 123 45 67",
      "address": "Moda Cd. No:12 D:3",
      "districtId": "<semt-id>"
    },
    "deliveryTypeId": "<gidiş-tipi-id>",
    "reference": "SIP-48213"
  }'

Sonra ne olur?

  • 201 ile siparişin id ve number bilgisi döner; sipariş kurye firmanızın operasyon ekranına düşer.
  • Aynı anahtarla farklı gövde gönderilirse 409 IDEMPOTENCY_MISMATCH döner. Anahtar 24 saat saklanır.
  • Durumu GET /me/orders/{id} ile okuyun ya da webhook ile dinleyin.
Node.js
import crypto from 'node:crypto'

// Ham gövdeyle: app.post('/courino', express.raw({ type: '*/*' }), …)
function verify(req, secret) {           // secret: whsec_… (tamamı)
  const sig = req.get('X-KOS-Signature')     // t=1761040000,v1=9f2c…
  const { t, v1 } = Object.fromEntries(sig.split(',').map((p) => p.split('=')))
  const mac = crypto.createHmac('sha256', secret)
    .update(`${t}.`).update(req.body).digest('hex')
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300
  return fresh && mac.length === v1?.length &&
    crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1))
}

Gelen olay

  • Gövde: { id, type, occurredAt, data: { order } }; type ör. order.delivered.
  • Aynı olay yeniden denenebilir: X-KOS-Delivery değerini saklayıp ikinciyi atlayın.
  • 2xx dönün. 410 Gone dönerseniz o ileti için deneme durur.
Başlarken

Üç adımda ilk siparişiniz

API, kurye firmanızın Courino müşteri portalındaki hesabınızla çalışır. Ayrı kayıt ya da sözleşme gerekmez.

Anahtarınızı oluşturun

  1. Müşteri portalına girin.
  2. Bilgilerim › Entegrasyon (API anahtarları) kartını açın.
  3. Anahtara bir ad verip Anahtar oluştur'a basın; yalnız bir kez gösterilir.
Adım adım anlatım →

Sipariş açın, olayları dinleyin

  1. POST /orders ile siparişi açın.
  2. Portalda Webhook (olay bildirimi) kartından adresinizi ekleyin.
  3. İmzayı doğrulayıp siparişin durumunu sisteminize yazın.
Webhook ekleme →
Bir bakışta

En çok kullanılan uçlar

Adreslerin hepsi https://client.courino.com/api/v1 altındadır. Tam liste, alanlar ve örnekler dokümanda.

GET/me/order-optionsSemtler ve gidiş tipleri (adreste districtId zorunlu)
POST/pricing/quoteFiyat teklifi (kaydetmez)
POST/ordersSipariş açar · Idempotency-Key
POST/me/orders/batchToplu sipariş, en çok 1000 satır
GET/me/ordersSiparişlerim; referans no, barkod ve tarihle arama
GET/me/orders/{id}Sipariş ayrıntısı ve durumu
PUT/me/orders/{id}Siparişi düzenler (henüz havuzdayken)
POST/me/orders/{id}/cancelİptal · Idempotency-Key
GET/me/orders/{id}/trackingCanlı kurye takibi
POST/me/orders/{id}/tracking-linkAlıcıya iletilecek takip bağlantısı
Kurallar ve sınırlar

Sürpriz yok: sınırlar baştan yazılı

120 / dk

Anahtar başına istek

Her yanıtta X-RateLimit-Limit, -Remaining ve -Reset; sınır aşılırsa 429 ve Retry-After.

5 + 5

Anahtar ve webhook

Hesap başına en çok 5 etkin API anahtarı ve 5 webhook aboneliği. Anahtar ve imza sırrı yalnız bir kez gösterilir.

Şifre = sıfırla

Hesap güvenliği

Hesabın şifresi değişince o hesabın anahtarlarının hepsi iptal olur. İptal ettiğiniz anahtar en geç 30 saniyede çalışmaz.

Kimin için

Kurye firmasıysanız

Büyük müşterinize "sistemine bağlanırız" deyin.

Müşteri kartından hesabına entegrasyon izni verin; müşteriniz anahtarını portaldan kendisi alır. Siparişler panelinize normal sipariş olarak düşer, fiyat müşterinin fiyat listesinden çıkar. Sızdığından şüphelendiğiniz anahtarı müşteri kartından iptal edersiniz.

Firmanızı ücretsiz kaydedin →
Geliştiriciyseniz

Kurye firmanız Courino kullanıyorsa hemen başlayın.

Portal hesabınıza entegrasyon izni verilmesini firmanızdan isteyin; sonra anahtarınızı oluşturup dokümandan ilerleyin. Takıldığınız yerde destek@courino.com'a yazın.

API dokümanına gidin →

Doküman hazır, deneme açık.

Swagger dokümanını açın ya da OpenAPI dosyasını indirip kendi aracınıza (Postman, Insomnia, kod üreticiler) yükleyin.

Doküman (Türkçe) Docs (English) openapi.yaml openapi.json