API başvurusu
Sipariş oluştur
https://kurye.firmaniz.com/api/v1/ordersSipariş 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_idmetinzorunluext: ile bulmak için kullanılır.1–100 karakter
external_codemetin · boş olabilirEn çok 100 karakter
restaurant_idtam sayıkoşullurestaurant_id ya da restaurant_code zorunludur; bağlıysa yok sayılır. Gövde yerine sorgu dizgisinde de gönderilebilir.restaurant_codemetinkoşullurestaurant_id yerine işletme kodu (ör. R001). Kodu kurye firmanız verir.customernesnecustomer.namemetin · boş olabilirEn çok 150 karakter
customer.phonemetin · boş olabilir+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
addressnesnezorunluaddress.textmetin · boş olabilirkoşulluneighborhood, street, building, district, city parçalarından birleştirilir; sonuç en az 3 karakter olmalıdır.En çok 500 karakter
address.citymetin · boş olabilirEn çok 60 karakter
address.districtmetin · boş olabilirEn çok 60 karakter
address.neighborhoodmetin · boş olabilirEn çok 100 karakter
address.streetmetin · boş olabilirEn çok 150 karakter
address.buildingmetin · boş olabilirNo: ile eklenir.En çok 40 karakter
address.floormetin · boş olabilirdetail verilmezse Kat 3, Daire 7 biçiminde adres ayrıntısına yazılır.En çok 20 karakter
address.apartmentmetin · boş olabilirEn çok 20 karakter
address.detailmetin · boş olabilirfloor ve apartment yok sayılır.En çok 255 karakter
address.directionsmetin · boş olabilirEn çok 500 karakter
address.latsayı · boş olabilir-90 ile 90 arası
address.lngsayı · boş olabilir-180 ile 180 arası
paymentnesnepayment.kindmetinDeğerler: cash, card, online, meal_card, other · Varsayılan: cash
payment.payment_type_idtam sayıkind yok sayılır.total_amountsayı0 ile 9999999 arası · Varsayılan: 0
collect_amountsayıtotal_amount kabul edilir. Önceden ödenmiş tiplerde her zaman 0.0 ile 9999999 arası
package_counttam sayı1 ile 50 arası · Varsayılan: 1
itemsnesne dizisi · boş olabilirEn çok 100 kalem.
items[].namemetinzorunlu1–200 karakter
items[].quantitysayı0 ile 1000 arası · Varsayılan: 1
items[].pricesayıEn az 0
items[].notemetin · boş olabilirEn çok 300 karakter
items[].optionsmetin dizisinotemetin · boş olabilirEn çok 1000 karakter
prep_minutestam sayı0 ile 600 arası
scheduled_attarih-saat · boş olabilir2026-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.
{
"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_REQUIRED401ks_ ile başlamıyor.API_KEY_INVALID401VALIDATION422fields içinde yazar.NOT_FOUND404OUT_OF_RANGE400OUT_OF_ZONE400PAYMENT_TYPE_NOT_FOUND400payment.kind türünde etkin bir ödeme tipi tanımlı değil.RESTAURANT_INACTIVE400OPEN_ORDER_LIMIT400CREDIT_LIMIT400INVALID_JSON400BODY_TOO_LARGE413{
"error": {
"code": "VALIDATION",
"message": "Adres zorunlu",
"fields": {
"address.text": "Adres zorunlu"
}
}
}429 RATE_LIMITED ve 5xx yanıtlarında kısa bir beklemeyle yeniden deneyin. Bkz. Yeniden deneme.