Kurye Firması Entegrasyonu

İşletmenin anlaştığı kurye firmasının kurye bilgisini ve konumunu kasa yazılımı nasıl bildirir.

Platform kurye hizmeti vermez; teslimatı işletme kendi kuryesiyle ya da anlaştığı firmayla yapar. Teslimatı anlaşmalı bir kurye firması yapıyorsa kurye bilgisini ve konumunu işletmenin kasa yazılımı yazar. Kurye firmasına işletmenin anahtarı verilmez ve firma bu uçlara kendi kimliğiyle erişmez. Ticari ilişki işletme ile firma arasındadır; platform bilgiyi yalnız iletir.

Bu sayfadaki uçlar

Her satır API referansındaki tam tanıma gider — alanlar, yanıt kodları ve deneme konsolu orada.

Akış

Teslime hazır siparişi okuyun: restoranda GET /orders?status=ready, Çarşı işletmesinde toplaması kapanmış sipariş (picking.completed: true). Webhook kullanıyorsanız order.updated olayı durum değişimini iletir.
Kuryeyi bildirin: PUT /orders/{id}/courier. Tekrar gönderim güncelleme yapar; ilk yazımın assignedAt değeri korunur.
Kurye yola çıkınca durumu ilerletin: POST /orders/{id}/status ile dispatch. Durum geçişi kurye uçlarında yapılmaz. Çarşı işletmesinde toplama kapanmadan dispatch yazılamaz.
Yolda konum yazın: PUT /orders/{id}/courier/location. Önerilen aralık 10 saniyedir.
Teslimde deliver yazın.

Kurye bildirimi

curl -X PUT "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/courier" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Örnek Kurye", "phone": "+905000000000", "externalId": "K-17", "company": "Örnek Kurye Firması", "arrivedAtStore": true }'

Konum

curl -X PUT "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/courier/location" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "latitude": 40.9127, "longitude": 38.3895, "heading": 135, "recordedAt": "2026-01-31T10:41:05Z" }'

Geliştirmeye test ortamında başlayın: test hesabındaki restoran ve Çarşı işletmesi kurye uçlarını da kabul eder.

Alanlar

Kurye isteği

Alan	Tip	Açıklama
`name`zorunlu	string	Kurye adı, 2–80 karakter.
`phone`	string	İsteğe bağlı; 10–15 rakam, başında + olabilir.
`externalId`	string	Kurye firmasının kurye kimliği, en çok 64 karakter.
`company`	string	Kurye firmasının adı, 1–64 karakter. Her istekte gönderin: `company` içermeyen bir `PUT` önceki firma adını siler.
`arrivedAtStore`	boolean	true ise kuryenin işletmeye ulaştığı an kaydedilir; ilk kayıt korunur.

Konum isteği

Alan	Tip	Açıklama
`latitude`zorunlu	number	-90 ile 90 arasında.
`longitude`zorunlu	number	-180 ile 180 arasında.
`heading`	number	Yön, 0 ile 359 arasında.
`recordedAt`	ISO 8601	Konumun alındığı an. Gelecekte ya da 10 dakikadan eskiyse reddedilmez, istek anına çekilir.

Kurye motokuryedir; araç alanı yoktur. Kurye adı ve telefonu yalnız işletmeye ve entegratöre döner; müşteriye gösterilmez. Sipariş nesnesinde bu bilgiler courier bloğunda döner: name, phone, externalId, firm (isteği yazan X-Integrator değeri), company (kurye firmasının adı; hiç gönderilmediyse null), assignedAt, arrivedAtStoreAt ve location. Kurye yanıtında ayrıca id (sipariş kimliği) bulunur; restoranda deliveryProvider alanı X-Integrator değerinden türeyen sağlayıcı kodunu verir.

Konum kişisel veridir. Sipariş başına yalnızca son konum saklanır, iz tutulmaz. Konum yazma ayrı hız grubundadır (konum) ve sipariş okuma kotasını tüketmez; ayrıntı için Servis Limitleri.

Kurallar ve hatalar

Alan	Tip	Açıklama
`409 order_closed`	kapalı sipariş	Teslim edilmiş ya da iptal edilmiş siparişe kurye veya konum yazılamaz; `current` siparişin durumunu verir.
`409 courier_not_set`	sıra	Konumdan önce `PUT /orders/{id}/courier` gönderilmeli.
`400 invalid_body`	alan	Yanıttaki `field` hangi alanın reddedildiğini söyler (`name`, `phone`, `externalId`, `company`, `latitude`, `longitude`, `heading`, `recordedAt`).
`404 not_found`	sipariş	Sipariş yok ya da bu işletmeye ait değil.

Müşteri iletişim verisi, sipariş teslim edildikten ya da iptal edildikten 2 saat sonra sipariş nesnesinden daraltılır: ad kısalır, telefon ve koordinat düşer, adres yalnız İlçe / İl olarak kalır, müşteri notu düşer. Kendi kayıtlarınızda da müşteri iletişim verisini bu süreden sonra tutmayın; süresiz saklama KVKK ölçülülük ilkesine aykırıdır.

Akış

Teslime hazır siparişi okuyun: restoranda GET /orders?status=ready, Çarşı işletmesinde toplaması kapanmış sipariş (picking.completed: true). Webhook kullanıyorsanız order.updated olayı durum değişimini iletir.

Kuryeyi bildirin: PUT /orders/{id}/courier. Tekrar gönderim güncelleme yapar; ilk yazımın assignedAt değeri korunur.

Kurye yola çıkınca durumu ilerletin: POST /orders/{id}/status ile dispatch. Durum geçişi kurye uçlarında yapılmaz. Çarşı işletmesinde toplama kapanmadan dispatch yazılamaz.

Yolda konum yazın: PUT /orders/{id}/courier/location. Önerilen aralık 10 saniyedir.

Teslimde deliver yazın.