🚴 Kurye Entegrasyonu Dokümantasyonu

📋 Genel Bakış

Bu webhook, yeni bir sipariş oluşturulduğunda sisteminize POST isteği olarak gönderilir. Webhook body'si JSON formatındadır ve tüm sipariş detaylarını içerir.

🔌 Endpoint Bilgileri

🔐 Authentication (Kimlik Doğrulama)

Restomenum POS sistemi, sipariş bilgilerini kurye firmasına gönderirken HTTP Authorization header'ı ile Bearer token kullanarak kimlik doğrulaması yapar. Bu token sayesinde kurye firması paketin hangi restorandan geldiğini tespit eder.

Headers

Örnek İstek (Restomenum POS tarafından gönderilir)

// Restomenum POS, siparişi kurye firmasına gönderir
POST https://kurye-firmasi.com/api/webhook
Headers:
  Content-Type: application/json
  Accept: application/json
  Authorization: Bearer abc123xyz_restaurant_unique_token

Body: {
  "id": "250306031353V2F52",
  "customer": { ... },
  "address": { ... },
  ...
}

Token ile Restoran Tespiti

// Kurye firması API'sinde token kontrolü
// Her token bir restorana ait olduğundan, 
// gelen Authorization token'a bakarak restoran tespit edilir

const token = request.headers.authorization.replace('Bearer ', '');

// Token veritabanında aranır
const restaurant = await findRestaurantByToken(token);

if (!restaurant) {
    return response.status(401).json({
        error: "Geçersiz authorization token"
    });
}

// Sipariş, tespit edilen restorana ait olarak işlenir
console.log(`Sipariş ${restaurant.name} restoranından geldi`);

⚙️ Entegrasyon Kurulumu

1. Kurye Firması Tarafı - Token Üretimi

Token Üretim Önerileri:

• En az 32 karakter uzunluğunda, rastgele bir string oluşturun
• Token'ı veritabanınızda restoran bilgisiyle ilişkilendirin
• Her token benzersiz olmalı ve sadece bir restoran için kullanılmalıdır
• Token'ları güvenli bir şekilde saklayın (şifrelenmiş)

// Token üretim örneği (Node.js)
const crypto = require('crypto');

function generateRestaurantToken(restaurantId) {
    const token = crypto.randomBytes(32).toString('hex');
    
    // Veritabanına kaydet
    await db.tokens.create({
        token: token,
        restaurantId: restaurantId,
        createdAt: new Date()
    });
    
    return token;
}

// Örnek: "a7f3c9e2b4d8f1a6c5e9d3b7f2a8c4e6d1b9f5a3c7e2d4b8f6a1c9e5d3b7f2a8"

2. Token Teslimi

Üretilen token, güvenli bir kanal üzerinden (e-posta, panel, vb.) restorana iletilmelidir.

3. Restoran Tarafı - Token Kaydı (Restomenum POS)

Restoran, kendisine teslim edilen Authorization token'ı Restomenum POS programında kaydetmelidir:

📱 Restomenum POS'ta Token Kaydetme:

1. Restomenum POS uygulamasını açın
2. Ayarlar menüsüne gidin
3. Entegrasyon sekmesini seçin
4. Kurye sayfasını açın (Eğer Bu sayfa yoksa lütfen destek ile iletişime geçin, müşteri için ekibimiz modülü aktif edecektir.)

1. Webhook URL kısmına oluşturdugunuz Webhook URL'sini yapıştırın, Authorization kısmına ise müşteriye oluşturdugunuz token'ı yapıştırın. Custom Headers kısmına ise gerekli header bilgilerini ekleyebilirsiniz.
2. Kaydet butonuna tıklayın

4. Otomatik İşleyiş

Token kaydedildikten sonra sistem otomatik olarak çalışır:

• ✅ Restoran sipariş oluşturduğunda (Otomatik yada manuel olarak)
• ✅ Restomenum POS otomatik olarak kaydedilen token'ı Authorization header'ına ekler
• ✅ Sipariş bilgileri + Authorization token kurye firmasına POST edilir
• ✅ Kurye firması token'dan restoran bilgisini tespit eder
• ✅ Kurye atanır ve teslimat başlatılır

5. Test ve Doğrulama

// Kurye firması API'sinde test endpoint'i
// Test siparişi göndererek entegrasyonu doğrulayın

POST /api/webhook/test
Headers:
  Authorization: Bearer [RESTAURANT_TOKEN]

Response:
{
    "success": true,
    "restaurant": {
        "id": "12345",
        "name": "Füreyya Restaurant",
        "phone": "0212XXXXXXX"
    },
    "message": "Token doğrulandı. Entegrasyon aktif."
}

📦 Request Body Yapısı

Ana Nesne

Customer Object (Müşteri)

Address Object (Adres)

Products Array (Ürünler)

CallbackUrls Object (Durum Bildirimi)

Restomenum POS, her sipariş için o siparişe özel callback URL'leri üretir ve bu nesnede gönderir. Kurye firması paketin durumu değiştiğinde ilgili URL'i çağırarak Restomenum'daki sipariş durumunu günceller. Kullanım detayları için Sipariş Durum Callback'leri bölümüne bakın.

💳 Ödeme Yöntemleri

Webhook'ta gelen paymentMethod değeri dinamiktir — restoran panelinde tanımlanan ödeme yöntemi adını taşır. Bu değer herhangi bir string olabilir; sistemde tanımlı ödeme yöntemine göre değişir.

Örnek değerler (sabit değildir):

• NAKIT - Nakit ödeme
• KREDI_KARTI - Kredi kartı ile ödeme
• ONLINE - Online ödeme
• ...ve sisteminizde tanımlı diğer ödeme yöntemleri

⚠️ Bu liste sabit değildir. Entegrasyonunuzda paymentMethod string değerini olduğu gibi işlemeniz önerilir.

📝 Örnek Request Body

{
    "id": "250306031353V2F52",
    "customer": {
        "fullName": "SAMET KARAKAYA",
        "phoneNumber": "05527283903",
        "phoneCode": null
    },
    "address": {
        "text": "BEM 330 SK ŞÜKÜR ST. G BLOK  ZİL 2",
        "description": null,
        "lat": null,
        "lon": null
    },
    "products": [
        {
            "id": "16571086",
            "name": "2 Kişilik Füreyya Menü",
            "price": "295",
            "quantity": "1",
            "options": null
        }
    ],
    "source": "sanaladisyon.com",
    "note": null,
    "totalAmount": "295",
    "totalDiscount": "0",
    "paymentMethod": "NAKIT",
    "platformCode": "109580",
    "dailyOrderNo": "0",
    "createdAt": "2025-03-06 03:00:17",
    "scheduledAt": null,
    "courierPhone": null,
    "callbackUrls": {
        "orderPickupUrl": "https://api.restomenum.app/integrations/kurye/{storeId}/{packetId}/pickup?token={token}",
        "orderDeliveredUrl": "https://api.restomenum.app/integrations/kurye/{storeId}/{packetId}/delivered?token={token}",
        "orderCancelUrl": "https://api.restomenum.app/integrations/kurye/{storeId}/{packetId}/cancel?token={token}"
    }
}

✅ Response Beklentisi

Webhook başarıyla işlendiğinde uygun HTTP status kodu döndürülmelidir:

200 OK

İstek başarıyla işlendi

400 Bad Request

Geçersiz veri formatı

401 Unauthorized

Yanlış veya eksik Authorization token

500 Internal Server Error

Sunucu hatası

🔄 Sipariş Durum Callback'leri

Sipariş webhook'u ile birlikte gönderilen callbackUrls nesnesi, kurye firmasının paketin durumunu Restomenum'a geri bildirmesi için kullanılır. Kurye, paketin durumu değiştiğinde ilgili URL'i çağırır; Restomenum siparişin durumunu otomatik günceller.

Callback Aksiyonları

Örnek Çağrı (Kurye firması tarafından gönderilir)

// Kurye paketi teslim aldığında orderPickupUrl çağrılır
POST https://api.restomenum.app/integrations/kurye/{storeId}/{packetId}/pickup?token={token}

// Body göndermeye gerek yoktur; token URL içindedir.
// Başarılı yanıt:
{
    "success": true,
    "status": "OnDelivery"
}

Yanıt Kodları

200 OK

Durum güncellendi ({ success: true, status: "..." })

400 Bad Request

Eksik parametre veya geçersiz aksiyon

401 Unauthorized

Geçersiz veya eksik token

404 Not Found

Paket bulunamadı

⚠️ Önemli Notlar