Kurye Entegrasyonu Webhook API Dokümantasyonu

Bu dokümantasyon, kurye firmalarının sipariş durumlarını güncellemeye yönelik webhook API'sini açıklar.

Genel Bakış

Kurye firmaları, siparişlerin teslim durumunu gerçek zamanlı olarak güncellemek için bu webhook endpoint'ini kullanabilir. Sistem, güncelleme sonrası restorana otomatik olarak socket ile bildirim gönderir.

Endpoint Bilgileri

URL

POST /api/v1/webhook/courier/status-update

Authentication

API çağrıları için restoran tarafından oluşturulan

API Key

kullanılması gerekmektedir.

İstek Formatı

Headers

Content-Type: application/json
x-api-key: {RESTAURANT_API_KEY}

Header	Tip	Zorunlu	Açıklama
`Content-Type`	string	Evet	`application/json` olmalıdır
`x-api-key`	string	Evet	Restoran tarafından sağlanan API anahtarı

Request Body

{
  "restaurantId": "string",
  "orderId": "string",
  "status": 1 | 2
}

Parametre	Tip	Zorunlu	Açıklama
`restaurantId`	string	Evet	MongoDB ObjectId formatında restoran ID
`orderId`	string	Evet	MongoDB ObjectId formatında sipariş ID
`status`	number	Evet	1: Teslim edilecek, 2: Teslim edildi

Status Değerleri

Status	Açıklama	Sipariş Durumu
`1`	Kurye siparişi teslim etmek üzere yola çıktı	`teslim-edilecek`
`2`	Sipariş müşteriye teslim edildi	`teslim-edildi`

Yanıt Formatı

Başarılı Yanıt (200 OK)

{
  "success": true,
  "message": "Sipariş durumu başarıyla güncellendi",
  "data": {
    "orderId": "507f1f77bcf86cd799439011",
    "status": "teslim-edilecek",
    "updatedAt": "2024-11-05T14:30:00.000Z"
  }
}

Hata Yanıtları

400 Bad Request - API Key Eksik

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Header'da API key gereklidir"
}

400 Bad Request - Geçersiz Restoran ID

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Geçersiz restoran ID"
}

400 Bad Request - Geçersiz Sipariş ID

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Geçersiz sipariş ID"
}

400 Bad Request - Sipariş Zaten Teslim Edilmiş/İptal Edilmiş

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Sipariş zaten teslim edildi veya iptal edildi"
}

404 Not Found - Kurye Entegrasyonu Bulunamadı

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Kurye entegrasyonu bulunamadı veya aktif değil"
}

404 Not Found - Sipariş Bulunamadı

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Bu restoran için sipariş bulunamadı"
}

500 Internal Server Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Sipariş güncellenemedi"
}

Örnek İstekler

cURL ile İstek

curl -X POST https://backend.paketsefim.com/api/v1/webhook/courier/status-update \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "restaurantId": "507f1f77bcf86cd799439011",
    "orderId": "507f1f77bcf86cd799439012",
    "status": 1
  }'

Node.js (Fetch API)

const response = await fetch('https://backend.paketsefim.com/api/v1/webhook/courier/status-update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY_HERE',
  },
  body: JSON.stringify({
    restaurantId: '507f1f77bcf86cd799439011',
    orderId: '507f1f77bcf86cd799439012',
    status: 1,
  }),
})

const data = await response.json()
console.log(data)

Python (Requests)

import requests

url = 'https://backend.paketsefim.com/api/v1/webhook/courier/status-update'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY_HERE'
}
payload = {
    'restaurantId': '507f1f77bcf86cd799439011',
    'orderId': '507f1f77bcf86cd799439012',
    'status': 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

PHP (cURL)

<?php
$url = 'https://backend.paketsefim.com/api/v1/webhook/courier/status-update';
$apiKey = 'YOUR_API_KEY_HERE';

$data = [
    'restaurantId' => '507f1f77bcf86cd799439011',
    'orderId' => '507f1f77bcf86cd799439012',
    'status' => 1
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
?>

Kurye Firmasına Gönderilen Sipariş Verisi

Restorana paket servis siparişi geldiğinde veya manuel olarak kurye çağırdığında, kurye firmasının API endpoint'ine aşağıdaki formatta veri gönderilir:

Sipariş Verisi Formatı

{
  "kuzeyOrderId": "507f1f77bcf86cd799439012",
  "restaurantId": "507f1f77bcf86cd799439011",
  "platform": "yemeksepeti",
  "status": "hazirlanacak",
  "orderType": "paket_servis",
  "createdAt": "2024-11-07T10:30:00.000Z",
  "paymentMethod": "card",
  "originalPaymentMethod": "Kapıda Kredi/Banka Kartı",
  "price": 125.5,
  "hazirlanmaSuresiDk": 15,
  "badges": ["Temassız Teslimat"],
  "orderNote": "İnce hamur olsun lütfen",
  "courierNote": "Kapı kodu: 1234",
  "customer": {
    "address": {
      "district": "Kadıköy",
      "city": "İstanbul",
      "neighborhood": "Fenerbahçe",
      "street": "Bağdat Caddesi",
      "buildingNo": "123",
      "floor": "4",
      "apartmentNo": "8",
      "detailedAddress": "Bağdat Caddesi No: 123, Kat: 4, Daire: 8, Fenerbahçe, Kadıköy, İstanbul",
      "directions": "Kapı kodu: 1234",
      "location": {
        "latitude": 40.9857,
        "longitude": 29.0347
      }
    },
    "details": {
      "name": "Ahmet Yılmaz",
      "phone": "+905551234567"
    }
  }
}

Alan Açıklamaları

Alan	Tip	Açıklama
`kuzeyOrderId`	string	Sistemdeki sipariş ID (MongoDB ObjectId)
`restaurantId`	string	Restoranın ID'si (MongoDB ObjectId)
`platform`	string	Siparişin geldiği platform: `getiryemek, yemeksepeti, migrosyemek, trendyolyemek, phone`
`status`	string	Siparişin mevcut durumu: `onaylanacak, hazirlanacak, yola-cikacak, vb.`
`orderType`	string	Sipariş tipi: `paket_servis` (sadece bu değer kullanılır)
`createdAt`	string (ISO 8601)	Siparişin oluşturulma tarihi
`paymentMethod`	string	Normalize edilmiş ödeme yöntemi: `card, cash, foodcard, getir, yemeksepeti, migros, trendyol`
`originalPaymentMethod`	string	Platform'dan gelen orjinal ödeme yöntemi bilgisi
`price`	number	Sipariş toplam tutarı (TL)
`hazirlanmaSuresiDk`	number	Tahmini hazırlanma süresi (dakika)
`badges`	string[]	Siparişe ait badge label'ları (detaylar aşağıda)
`orderNote`	string	null
`courierNote`	string	null
`customer.address`	object	Müşteri teslimat adresi bilgileri
`customer.details`	object	Müşteri iletişim bilgileri

Badge Bilgileri

badges

alanı siparişe ait özel işaretlerin label'larını içeren bir string dizisidir.

Format:

"badges": ["Yeşili Koru", "Temassız Teslimat", "Kapıyı Çalma"]

Platform Bazlı Badge Label'ları:

MigrosYemek:
- ```
saveGreen
```
  → "Yeşili Koru"
- ```
contactlessDelivery
```
  → "Temassız Teslimat"
- ```
ringDoorBell: false
```
  → "Zili Çalma"
GetirYemek:
- ```
doNotKnock
```
  → "Kapıyı Çalma"
- ```
dropOffAtDoor
```
  → "Kapıya Bırak"
- ```
isEcoFriendly
```
  → "Çevre Dostu"
YemekSepeti: Şu anda badge desteği yok
TrendyolYemek: Şu anda badge desteği yok
Phone/Table: Şu anda badge desteği yok

Badge'ler platform verilerine göre otomatik olarak oluşturulur ve boş array (

[]

) olarak gönderilebilir.

Sipariş Notları

Sipariş notları iki farklı türde gönderilir:

Order Note (Sipariş Notu)

orderNote

alanı müşteri tarafından siparişe eklenen genel notları içerir. Bu notlar siparişin hazırlanması ile ilgili özel talimatlar içerebilir.

Courier Note (Kurye Notu)

courierNote

alanı teslimat için özel talimatları içerir. Bu notlar kurye için adres bulma, kapı kodu, zil çalma gibi bilgiler içerebilir.

Format:

{
  "orderNote": "İnce hamur olsun lütfen",
  "courierNote": "Kapı kodu: 1234, Yeşil kapı"
}

Her iki alan da opsiyoneldir ve not yoksa

null

olarak gönderilir.

İş Akışı

Sipariş Oluşturma: Restoran siparişi oluşturur ve kurye firmasına yukarıdaki formatta otomatik olarak bildirilir
Yola Çıkış: Kurye siparişi teslim etmek üzere yola çıktığında
```
status: 1
```
ile webhook'u çağırır
Teslim: Sipariş teslim edildiğinde
```
status: 2
```
ile webhook'u çağırır
Platform Güncellemesi: Eğer sipariş yemek platformlarından (GetirYemek, YemekSepeti, MigrosYemek, TrendyolYemek) geliyorsa, otomatik olarak o platformun API'sine de durum güncellemesi gönderilir

Güvenlik ve Kısıtlamalar

Güvenlik

✅ API Key kontrolü yapılır
✅ Restoran ve sipariş ilişkisi doğrulanır
✅ Sadece aktif entegrasyonlar güncelleme yapabilir
✅ Teslim edilmiş veya iptal edilmiş siparişler güncellenemez

Rate Limiting

API rate limiting uygulanmamaktadır, ancak makul kullanım beklenmektedir.

Retry Stratejisi

Webhook çağrısı başarısız olursa 3 kez yeniden denenir
Exponential backoff stratejisi kullanılır (1s, 2s, 4s)
5xx hataları ve network hataları için retry yapılır
4xx hataları için retry yapılmaz

Platform Entegrasyonu

Webhook çağrıldığında, sipariş türüne göre otomatik platform güncellemesi yapılır:

Telefon (
```
phone
```
) siparişleri için sadece kendi veritabanımız güncellenir, platform API'sine istek atılmaz
Yemek platformlarından gelen siparişler için o platformun API'sine otomatik güncelleme gönderilir

Önemli Notlar:

Platform güncellemesi başarısız olsa bile kendi veritabanımız güncellenir
Platform hataları loglanır ancak webhook başarılı yanıt döner
Bu sayede kurye firması her durumda işlemini tamamlayabilir

Destek

Herhangi bir sorun veya soru için lütfen bizimle iletişime geçin:

Email: destek@paketsefim.com
Teknik Destek: +90 XXX XXX XX XX

Versiyon Geçmişi

Versiyon	Tarih	Değişiklikler
1.1.0	2024-11-05	Platform entegrasyonu eklendi (GetirYemek, YemekSepeti, MigrosYemek, TrendyolYemek)
1.0.0	2024-11-05	İlk sürüm yayınlandı

Sık Sorulan Sorular

API Key nasıl alınır?

API Key, restoran tarafından kurye entegrasyonu kurulumu sırasında otomatik olarak oluşturulur.

Aynı sipariş için birden fazla güncelleme yapılabilir mi?

Evet, ancak sipariş

teslim-edildi

veya

cancelled

durumuna geçtikten sonra güncellenemez.

Webhook başarısız olursa ne olur?

Sistem otomatik olarak 3 kez yeniden deneme yapar. Tüm denemeler başarısız olursa hata loglanır.

Status 1 ve 2 arasında başka durum var mı?

Hayır, kurye entegrasyonu için sadece iki durum tanımlanmıştır: Yola çıkış (1) ve Teslim (2).

Platform güncellemesi başarısız olursa ne olur?

Platform güncellemesi başarısız olsa bile webhook başarılı yanıt döner ve kendi veritabanımız güncellenir. Bu sayede kurye firması işlemini tamamlayabilir. Platform hataları loglanır ve teknik ekip tarafından incelenir.

Webhook API Dokümantasyonu