📋 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`);
- 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:
- Restomenum POS uygulamasını açın
- Ayarlar menüsüne gidin
- Entegrasyon sekmesini seçin
- 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.)
Webhook URLkı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 Headerskısmına ise gerekli header bilgilerini ekleyebilirsiniz.- 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."
}
- 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
- 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.