🔔 Webhook API Dokümantasyonu

Sipariş Bildirimi Entegrasyonu

📋 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

Method: POST

Content-Type: application/json

Accept: application/json

Authorization: Bearer {API_KEY}

🔐 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.

Önemli: Authorization token, kurye firması tarafından her restoran için üretilir ve restorana teslim edilir.

Restoran bu token'ı Restomenum POS sistemine kaydeder. Sistem, sipariş oluşturulduğunda bu token'ı otomatik olarak isteklere ekler.

Headers

Header Değer Açıklama
Content-Type application/json İstek body'sinin JSON formatında olduğunu belirtir
Accept application/json Response'un JSON formatında beklediğini belirtir
Authorization Bearer {RESTAURANT_TOKEN} Restoran için benzersiz token - Paketin hangi restorandan geldiğini belirtir

Ö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`);
🔑 Authorization Token Akışı:
  • 1. Kurye Firması: Her restoran için benzersiz bir token üretir
  • 2. Token Teslimi: Üretilen token güvenli şekilde restorana iletilir
  • 3. Restoran: Token'ı Restomenum POS'a kaydeder (Ayarlar → Entegrasyon)
  • 4. Otomatik Gönderim: Restomenum POS her siparişte bu token'ı Authorization header'ında gönderir
  • 5. Kurye Firması: Gelen token'dan hangi restorandan sipariş geldiğini anlar

⚙️ Entegrasyon Kurulumu

1. Kurye Firması Tarafı - Token Üretimi

Görev: Her restoran için benzersiz bir Authorization Bearer Token üretilmelidir.

Amaç: Gelen siparişlerin hangi restorandan geldiğini tespit etmek.

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."
}
🔑 Önemli Bilgiler:
  • Her restoran için farklı bir token kullanılmalıdır
  • Token'lar kurye firması tarafından üretilir ve restorana verilir
  • Restoran token'ı sadece bir kere kaydeder, sonrası otomatik çalışır
  • Token sayesinde kurye firması hangi restorandan sipariş geldiğini anlar
  • Yanlış token durumunda 401 Unauthorized hatası döner
  • Token'lar gerektiğinde yenilenebilir (restoran yeni token'ı tekrar kaydeder)
  • Eğer sipariş daha önce gönderildiyse status 200 dönüş yapılması gerek.

📦 Request Body Yapısı

Ana Nesne

Alan Tip Durum Açıklama
id string Zorunlu Sipariş benzersiz kimlik numarası
customer object Zorunlu Müşteri bilgilerini içeren nesne
address object Zorunlu Teslimat adresi bilgilerini içeren nesne
products array Zorunlu Sipariş edilen ürünlerin listesi
source string Zorunlu Siparişin geldiği platform/kaynak
note string/null Opsiyonel Sipariş notu (varsa)
totalAmount string Zorunlu Toplam tutar (TL)
totalDiscount string Zorunlu Toplam indirim tutarı (TL)
paymentMethod string Zorunlu Ödeme yöntemi
platformCode string Zorunlu Platform kodu
dailyOrderNo string Zorunlu Günlük sipariş numarası
createdAt string Zorunlu Sipariş oluşturulma tarihi (YYYY-MM-DD HH:MM:SS)
scheduledAt string/null Opsiyonel Planlanmış teslimat zamanı (varsa)
courierPhone string/null Opsiyonel Kurye telefon numarası (varsa)

Customer Object (Müşteri)

Alan Tip Durum Açıklama
fullName string Zorunlu Müşterinin tam adı
phoneNumber string Zorunlu Müşteri telefon numarası
phoneCode string/null Opsiyonel Telefon ülke kodu (varsa)

Address Object (Adres)

Alan Tip Durum Açıklama
text string Zorunlu Adres metni
description string/null Opsiyonel Adres açıklaması/tarifi (varsa)
lat string/null Opsiyonel Enlem (GPS koordinatı)
lon string/null Opsiyonel Boylam (GPS koordinatı)

Products Array (Ürünler)

Alan Tip Durum Açıklama
id string Zorunlu Ürün benzersiz kimlik numarası
name string Zorunlu Ürün adı
price string Zorunlu Birim fiyat (TL)
quantity string Zorunlu Ürün adedi
options string/null Opsiyonel Ürün seçenekleri/varyasyonları (varsa)

💳 Ödeme Yöntemleri

Webhook'ta gelebilecek paymentMethod değerleri:

  • NAKIT - Nakit ödeme
  • KREDI_KARTI - Kredi kartı ile ödeme
  • ONLINE - Online ödeme

📝 Ö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
}

✅ 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ı

⚠️ Önemli Notlar

Dikkat Edilmesi Gerekenler:
  • Karakter Kodlaması: Türkçe karakterler webhook'ta Unicode escape formatında gelebilir. Bunları düzgün decode ettiğinizden emin olun.
  • Null Değerler: Bazı alanlar null olabilir. Kodunuzda null kontrolü yapmayı unutmayın.
  • Fiyat Formatı: Tüm fiyat değerleri string formatında ve TL cinsindendir.
  • Tarih Formatı: createdAt ve scheduledAt alanları YYYY-MM-DD HH:MM:SS formatındadır.
  • Günlük Sipariş No: dailyOrderNo değeri "0" olabilir, bu durumda muhtemelen henüz atanmamış demektir.