İçeriğe geç
KuryeSoft

API başvurusu

Sipariş oluştur

Kurye firmasına yeni bir paket siparişi gönderir; sistem uygun kuryeyi kendisi atar.
POSThttps://kurye.firmaniz.com/api/v1/orders

Sipariş pending (Bekliyor) durumunda yazılır; kurye ataması kurye firmasının atama senaryosuna göre başlar (çoğunlukla hemen). Paket hazır olduğunda Hazır işaretle çağrısını yapın. Bkz. Hazırlık süresi.

Aynı siparişi iki kez açmaz. Aynı işletme için aynı external_id ile ikinci kez gönderilen istek yeni sipariş açmaz, mevcut siparişi 200 ile döndürür. Bu yüzden zaman aşımı ya da ağ hatasında isteği aynı gövdeyle güvenle yeniden gönderebilirsiniz. Yinelenen istekteki değişiklikler (ör. yeni tutar) uygulanmaz.

Teslimat konumunu (address.lat, address.lng) gönderin. Konumsuz siparişte mesafe ve ücret hesaplanamaz: firmanın fiyat profili konuma dayanıyorsa sipariş OUT_OF_ZONE ile reddedilir, dayanmıyorsa alınır ama kurye firması haritada konumu işaretleyene kadar otomatik atama bekler. API adres metninden konum bulmaz.

İstek gövdesi

Content-Type: application/json. Belirtilmeyen alanlar varsayılan değeriyle kabul edilir; tanımsız alanlar yok sayılır.

external_idmetinzorunlu
Siparişin sizin sisteminizdeki benzersiz kimliği. Yinelenen gönderimleri ayıklamak ve siparişi sonradan ext: ile bulmak için kullanılır.

1–100 karakter

external_codemetin · boş olabilir
Panelde ve kurye uygulamasında gösterilecek kısa sipariş numaranız (ör. adisyon no).

En çok 100 karakter

restaurant_idtam sayıkoşullu
İşletmenin kimliği. Anahtarınız bir işletmeye bağlı değilse restaurant_id ya da restaurant_code zorunludur; bağlıysa yok sayılır. Gövde yerine sorgu dizgisinde de gönderilebilir.
restaurant_codemetinkoşullu
restaurant_id yerine işletme kodu (ör. R001). Kodu kurye firmanız verir.
customernesne
Müşteri.
customer.namemetin · boş olabilir
Müşterinin adı.

En çok 150 karakter

customer.phonemetin · boş olabilir
Müşterinin telefonu. +90 532 123 45 67, 905321234567, 5321234567 gibi biçimler kabul edilir ve 05321234567 olarak saklanır. Kurye firması "Müşteri telefonu zorunlu" ayarını açtıysa zorunludur.

En çok 30 karakter

addressnesnezorunlu
Teslimat adresi.
address.textmetin · boş olabilirkoşullu
Tam adres metni. Verilmezse neighborhood, street, building, district, city parçalarından birleştirilir; sonuç en az 3 karakter olmalıdır.

En çok 500 karakter

address.citymetin · boş olabilir
İl.

En çok 60 karakter

address.districtmetin · boş olabilir
İlçe.

En çok 60 karakter

address.neighborhoodmetin · boş olabilir
Mahalle.

En çok 100 karakter

address.streetmetin · boş olabilir
Cadde/sokak.

En çok 150 karakter

address.buildingmetin · boş olabilir
Bina numarası; adres metnine No: ile eklenir.

En çok 40 karakter

address.floormetin · boş olabilir
Kat. detail verilmezse Kat 3, Daire 7 biçiminde adres ayrıntısına yazılır.

En çok 20 karakter

address.apartmentmetin · boş olabilir
Daire.

En çok 20 karakter

address.detailmetin · boş olabilir
Adres ayrıntısı (bina adı, kat, daire). Verilirse floor ve apartment yok sayılır.

En çok 255 karakter

address.directionsmetin · boş olabilir
Kuryeye adres tarifi.

En çok 500 karakter

address.latsayı · boş olabilir
Teslimat konumu (enlem). Önerilir.

-90 ile 90 arası

address.lngsayı · boş olabilir
Teslimat konumu (boylam). Önerilir.

-180 ile 180 arası

paymentnesne
Ödeme. Hiçbiri verilmezse kapıda nakit kabul edilir.
payment.kindmetin
Ödeme türü; bu türdeki ilk etkin ödeme tipi kullanılır.

Değerler: cash, card, online, meal_card, other · Varsayılan: cash

payment.payment_type_idtam sayı
Tür yerine doğrudan ödeme tipi (Ödeme tiplerini listele). Verilirse kind yok sayılır.
total_amountsayı
Sipariş tutarı (TL).

0 ile 9999999 arası · Varsayılan: 0

collect_amountsayı
Kuryenin kapıda tahsil edeceği tutar (TL). Verilmezse tahsilatlı ödeme tiplerinde total_amount kabul edilir. Önceden ödenmiş tiplerde her zaman 0.

0 ile 9999999 arası

package_counttam sayı
Paket sayısı.

1 ile 50 arası · Varsayılan: 1

itemsnesne dizisi · boş olabilir
Ürünler. Kurye uygulamasında ve panelde gösterilir.

En çok 100 kalem.

items[].namemetinzorunlu
Ürün adı.

1–200 karakter

items[].quantitysayı
Adet.

0 ile 1000 arası · Varsayılan: 1

items[].pricesayı
Birim fiyat (TL).

En az 0

items[].notemetin · boş olabilir
Ürün notu.

En çok 300 karakter

items[].optionsmetin dizisi
Seçenekler (ör. "Acısız"). En çok 30, her biri en çok 200 karakter.
notemetin · boş olabilir
Sipariş notu; kuryeye ve panele gösterilir.

En çok 1000 karakter

prep_minutestam sayı
Hazırlık süresi (dakika). Verilmezse firmanın varsayılanı (genellikle 15 dk) kullanılır.

0 ile 600 arası

scheduled_attarih-saat · boş olabilir
İleri tarihli sipariş: hazırlığın başlayacağı an (ISO 8601, ör. 2026-11-21T19:30:00+03:00). Kurye ataması bu anda başlar; sipariş scheduled_at + prep_minutes anında hazır kabul edilir.

Örnek istek

curl -X POST "https://kurye.firmaniz.com/api/v1/orders" \
  -H "X-Api-Key: $KURYESOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "POS-10452",
    "external_code": "A-52",
    "customer": {
      "name": "Ayşe Yılmaz",
      "phone": "05321234567"
    },
    "address": {
      "text": "Caferağa Mah. Moda Cad. No:12 Kadıköy",
      "floor": "3",
      "apartment": "7",
      "directions": "Eczanenin yanındaki bina",
      "lat": 40.9969,
      "lng": 29.0342
    },
    "payment": {
      "kind": "cash"
    },
    "total_amount": 285.5,
    "items": [
      {
        "name": "Tavuk Dürüm",
        "quantity": 2,
        "price": 120
      },
      {
        "name": "Ayran",
        "quantity": 1,
        "price": 45.5,
        "options": [
          "Büyük"
        ]
      }
    ],
    "note": "Zili çalmayın",
    "prep_minutes": 15
  }'

Yanıt

201 Oluşturuldu

Sipariş oluşturuldu. Gövde bir sipariş nesnesidir.

201 · application/json
{
  "id": 1842,
  "code": "2611200042",
  "external_id": "POS-10452",
  "status": "pending",
  "status_label": "Bekliyor",
  "restaurant_id": 1,
  "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
  "courier": null,
  "distance_m": 1754,
  "eta_at": null,
  "delivery_fee": 70,
  "total_amount": 285.5,
  "collect_amount": 285.5,
  "created_at": "2026-11-20T18:10:32.000Z",
  "assigned_at": null,
  "picked_up_at": null,
  "delivered_at": null,
  "cancelled_at": null,
  "cancel_reason": null
}

200 Yinelenen gönderim

Bu external_id ile sipariş zaten var; mevcut sipariş olduğu gibi döner. Gövde bir sipariş nesnesidir.

Hatalar

Hata gövdesi her zaman { "error": { "code", "message", "fields" } } biçimindedir. Bu uçta karşılaşabileceğiniz kodlar (bütün liste için Hatalar):

API_KEY_REQUIRED
HTTP:401
Anlamı:İstekte API anahtarı yok ya da ks_ ile başlamıyor.
API_KEY_INVALID
HTTP:401
Anlamı:Anahtar yanlış, silinmiş ya da pasif.
VALIDATION
HTTP:422
Anlamı:Eksik ya da hatalı alan. Hangi alanın neden reddedildiği fields içinde yazar.
NOT_FOUND
HTTP:404
Anlamı:Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.
OUT_OF_RANGE
HTTP:400
Anlamı:Adres, firmanın tanımladığı en fazla teslimat mesafesinin dışında.
OUT_OF_ZONE
HTTP:400
Anlamı:Adres hizmet bölgesinin dışında ya da ücret hesaplanamadı (çoğu zaman konum eksik).
PAYMENT_TYPE_NOT_FOUND
HTTP:400
Anlamı:payment.kind türünde etkin bir ödeme tipi tanımlı değil.
RESTAURANT_INACTIVE
HTTP:400
Anlamı:İşletme pasif durumda; sipariş alınmıyor.
OPEN_ORDER_LIMIT
HTTP:400
Anlamı:İşletmenin aynı anda açık sipariş sınırı doldu.
CREDIT_LIMIT
HTTP:400
Anlamı:İşletmenin cari borcu firmanın belirlediği sınırı aştı.
INVALID_JSON
HTTP:400
Anlamı:Gövde geçerli bir JSON değil.
BODY_TOO_LARGE
HTTP:413
Anlamı:Gövde 2 MB'tan büyük.
422 · application/json
{
  "error": {
    "code": "VALIDATION",
    "message": "Adres zorunlu",
    "fields": {
      "address.text": "Adres zorunlu"
    }
  }
}
İpucu:

429 RATE_LIMITED ve 5xx yanıtlarında kısa bir beklemeyle yeniden deneyin. Bkz. Yeniden deneme.