POS API Dokümantasyonu

HizirYemek POS API, POS sistemlerinin siparişleri otomatik almasını ve sipariş durumlarını gerçek zamanlı güncellemesini sağlar.

Base URL

https://www.hiziryemek.com/api/v1/pos-webhook

POST/apply

Entegrasyon Başvurusu

Entegrasyon sürecinin ilk adımıdır. Başvurunuz onaylandığında size özel x-webhook-secret anahtarı iletilir. Bu endpoint herkese açıktır, kimlik doğrulama gerektirmez. Dilerseniz başvuru formunu da kullanabilirsiniz.

Request Body

Alan	Tip	Zorunlu	Açıklama
companyName	string	Evet	Firma adı
contactName	string	Evet	Yetkili kişinin adı soyadı
email	string	Evet	İletişim e-posta adresi
phone	string	Evet	İletişim telefon numarası
apiBaseUrl	string	Evet	Siparişleri alacağınız API adresi. Yeni siparişler `{apiBaseUrl}/orders` adresine POST edilir.
description	string	Hayır	Entegrasyon hakkında kısa bilgi

Not: Bu endpoint 15 dakikada en fazla 5 başvuru kabul eder. Limit aşılırsa 429 döner.

Başarılı Yanıt

1{
2  "success": true,
3  "message": "Başvurunuz alınmıştır. En kısa sürede sizinle iletişime geçeceğiz.",
4  "data": {
5    "id": "507f1f77bcf86cd799439099"
6  }
7}

Kod Örneği

1curl -X POST https://www.hiziryemek.com/api/v1/pos-webhook/apply \
2  -H "Content-Type: application/json" \
3  -d '{
4    "companyName": "Örnek POS A.Ş.",
5    "contactName": "Ahmet Yılmaz",
6    "email": "[email protected]",
7    "phone": "0 532 123 45 67",
8    "apiBaseUrl": "https://api.ornekpos.com",
9    "description": "Entegrasyon hakkında kısa bilgi"
10  }'

Kimlik Doğrulama

Tüm isteklerde x-webhook-secret header'ı zorunludur. Bu anahtar, başvurunuz onaylandıktan sonra size iletilecektir.

1// Her istekte bu header gereklidir
2x-webhook-secret: YOUR_WEBHOOK_SECRET
3
4// Ayrıca her istekte restaurantId alanı zorunludur.
5// Bu alan hangi restoranın verisi olduğunu belirtir.

Anahtarınız geçerli olsa bile, istek attığınız restoranın sizinle aktif bir bağlantısı yoksa 401 dönersiniz. Bağlantı restoran panelinden pasife alınabilir. Ayrıca yeni siparişlerin size iletilmesi için bağlantının "bağlı" durumda olması gerekir — bağlantı aktif ama bağlı değilse yukarıdaki endpoint'leri çağırabilirsiniz fakat o restoranın siparişleri size gönderilmez.

POST/webhook

Sipariş Durumu Güncelleme

POS sisteminizden sipariş durumunu güncellemek için bu endpoint'i kullanın.

Request Body

Alan	Tip	Zorunlu	Açıklama
restaurantId	string	Evet	HizirYemek restoran ID
orderId	string	*	HizirYemek sipariş ID
posOrderId	string	*	POS tarafındaki sipariş ID
status	string	Hayır	Yeni sipariş durumu

* orderId veya posOrderId alanlarından en az biri zorunludur.

status alanı opsiyoneldir. Hiç göndermezseniz sipariş durumu değişmez, yalnızca siparişin size ulaştığı kayda geçer. Listede olmayan bir değer gönderirseniz istek yine 200 döner ama durum güncellenmez — yazım hatasında sessiz kalmamak için gönderdiğiniz değeri aşağıdaki listeyle karşılaştırın.

Geçerli Status Değerleri

pendingconfirmedpreparingon_the_waydeliveredcancelled

Başarılı Yanıt

1{
2  "success": true,
3  "message": "Webhook işlendi"
4}

Kod Örnekleri

1curl -X POST https://www.hiziryemek.com/api/v1/pos-webhook/webhook \
2  -H "Content-Type: application/json" \
3  -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
4  -d '{
5    "restaurantId": "507f1f77bcf86cd799439011",
6    "orderId": "507f1f77bcf86cd799439012",
7    "status": "preparing"
8  }'

GET/restaurant-status

Restoran Aktiflik Durumu Sorgulama

Restoranın şu an açık olup olmadığını sorgulamak için bu endpoint'i kullanın. Çalışma saatleri bilgisi de yanıtta döner.

Query Parametreleri

Alan	Tip	Zorunlu	Açıklama
restaurantId	string	Evet	HizirYemek restoran ID

Yanıt Alanları

Alan	Tip	Açıklama
restaurantId	string	Sorgulanan restoranın ID'si
restaurantName	string	Restoran adı
isOpen	boolean	Restoran şu an açık mı (true = açık, false = kapalı)
closed	boolean	Kalıcı kapatma durumu
tempClosed	boolean	Geçici kapatma durumu
workingHours	array	Çalışma saatleri — `{ day: 0-6, open, close }`

Başarılı Yanıt

1{
2  "success": true,
3  "data": {
4    "restaurantId": "507f1f77bcf86cd799439011",
5    "restaurantName": "Karadeniz Pide Salonu",
6    "isOpen": true,
7    "closed": false,
8    "tempClosed": false,
9    "workingHours": [
10      {
11        "day": 1,
12        "open": "09:00",
13        "close": "22:00"
14      },
15      {
16        "day": 2,
17        "open": "09:00",
18        "close": "22:00"
19      }
20    ]
21  }
22}

Kod Örnekleri

1curl "https://www.hiziryemek.com/api/v1/pos-webhook/restaurant-status?restaurantId=507f1f77bcf86cd799439011" \
2  -H "x-webhook-secret: YOUR_WEBHOOK_SECRET"

PUT/restaurant-status

Restoran Aktiflik Durumu Değiştirme

Restoranı geçici olarak açmak veya kapatmak için bu endpoint'i kullanın. Kalıcı olarak kapatılmış restoranlar POS üzerinden açılamaz.

Request Body

Alan	Tip	Zorunlu	Açıklama
restaurantId	string	Evet	HizirYemek restoran ID
isOpen	boolean	Evet	true = restoranı aç, false = geçici olarak kapat

Başarılı Yanıt

1{
2  "success": true,
3  "message": "Restoran geçici olarak kapatıldı",
4  "data": {
5    "restaurantId": "507f1f77bcf86cd799439011",
6    "isOpen": false,
7    "tempClosed": true
8  }
9}

Not: Kalıcı olarak kapatılmış restoranlar (closed: true) bu endpoint ile açılamaz. Bu durumda 400 hatası döner.

Kod Örnekleri

1curl -X PUT https://www.hiziryemek.com/api/v1/pos-webhook/restaurant-status \
2  -H "Content-Type: application/json" \
3  -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
4  -d '{
5    "restaurantId": "507f1f77bcf86cd799439011",
6    "isOpen": false
7  }'

PUSHHizirYemek → POS

Yeni Sipariş Alımı

Yeni bir sipariş oluşturulduğunda HizirYemek, sizin API'nize aşağıdaki formatta bir POST isteği gönderir.

Endpoint

POST { sizin apiBaseUrl }/orders

x-webhook-secret header'ı ile gönderilir.

Yanıt Vermeniz Gereken Süre ve Tekrar Denemeler

Aynı sipariş size birden fazla kez gönderilebilir.

Sistemimiz siparişi 10 saniye içinde 2xx ile yanıtlamanızı bekler. Bu sürede yanıt alamazsak veya yanıt 2xx değilse sipariş kaybolmasın diye aynı payload yeniden gönderilir. Bu yüzden kaydı orderId üzerinden tekilleştirmeniz (idempotency) zorunludur — aksi halde mutfakta aynı sipariş için birden fazla fiş kesilir.

Kural	Değer
Beklenen yanıt	`2xx` HTTP durum kodu
Zaman aşımı	10 saniye
İlk tekrar denemesi	Başarısız gönderimden en erken 3 dakika sonra
Tekrar sıklığı	2 dakikada bir kontrol edilir
Azami deneme	5 (sonrasında sipariş aktarılamamış sayılır ve operasyon ekibimize düşer)
Denemeyi durduran şey	Bizden `2xx` almamız veya sizin `POST /webhook` ile o siparişe dair durum bildirmeniz

İptal edilmiş veya teslim edilmiş siparişler için tekrar denemesi yapılmaz.

Payload Alanları

Alan	Tip	Açıklama
restaurantId	string	HizirYemek restoran ID
orderId	string	HizirYemek sipariş ID
orderNumber	string	Sipariş numarası (ör: `HY-20260413-0005`)
customer	object \| null	Müşteri bilgisi — `{ name, phone }`
items	array	Sipariş kalemleri (detay aşağıda)
subtotal	number	Ara toplam
deliveryFee	number	Teslimat ücreti
discount	number	Kupon ve kampanya kaynaklı toplam indirim. İndirim yoksa `0`'dır.
total	number	Müşterinin ödeyeceği genel toplam — `subtotal + deliveryFee - discount`
deliveryAddress	object \| yok	Teslimat adresi (detay aşağıda). Gel al (orderType: "pickup") siparişlerde bu alan hiç gönderilmez.
customerNote	string \| null	Müşteri notu (opsiyonel)
orderType	string	`"delivery"` = paket servis (kurye adrese getirir) \| `"pickup"` = gel al (müşteri restorandan alır). pickup siparişlerde `deliveryAddress` alanı GÖNDERİLMEZ ve `deliveryFee` her zaman 0'dır.
scheduledFor	string \| null	İleri tarihli sipariş ise müşterinin seçtiği teslim/hazır olma anı (ISO-8601). `null` ise "en kısa sürede" siparişidir. Dolu olduğunda sipariş size bu andan yaklaşık 30 dakika önce iletilir — yani webhook'u aldığınızda hazırlığa başlayabilirsiniz.
paymentMethod	string	`"online"` \| `"cash_on_delivery"` \| `"card_on_delivery"` \| `"meal_card_on_delivery"`
mealCardProvider	string \| null	Yemek kartı markası — sadece `"meal_card_on_delivery"` siparişlerinde dolu: `"metropol"` \| `"edenred"` \| `"pluxee"`
createdAt	string	Sipariş oluşturulma tarihi (ISO 8601)

items[] Yapısı

Alan	Tip	Açıklama
productId	string	Ürün ID
name	string	Ürün adı
quantity	number	Adet
unitPrice	number	Birim fiyat
options	array	Seçenekler — `{ groupName, choiceName, price }`
removedIngredients	string[]	Çıkarılan malzemeler
extras	array	Ekstra malzemeler — `{ name, price }`
itemTotal	number	Kalem toplam tutarı

deliveryAddress Yapısı

Alan	Tip	Açıklama
title	string	Adres başlığı (ör: "Ev", "İş")
address	string	Tam adres metni
neighborhood	string	Mahalle
district	string	İlçe
city	string	Şehir
buildingName	string	Bina adı
buildingNo	string	Bina numarası
floor	string	Kat
apartmentNo	string	Daire numarası
elevator	string	Asansör durumu
directions	string	Yol tarifi / ek not
location	object	GeoJSON konum — `{ type: "Point", coordinates: [lng, lat] }`

Payload Örneği

Üç varyantı da karşılamaya hazır olun. Gel Al siparişlerinde deliveryAddress alanı hiç gönderilmez (JSON'da yer almaz, null değildir) — alanı zorunlu varsayan bir ayrıştırıcı hata verir.

1{
2  "restaurantId": "507f1f77bcf86cd799439011",
3  "orderId": "507f1f77bcf86cd799439012",
4  "orderNumber": "HY-20260413-0005",
5  "customer": {
6    "name": "Ahmet Yılmaz",
7    "phone": "0 532 123 45 67"
8  },
9  "items": [
10    {
11      "productId": "507f1f77bcf86cd799439013",
12      "name": "Orta Boy Pizza Sever Menü",
13      "quantity": 1,
14      "unitPrice": 400.35,
15      "options": [
16        {
17          "groupName": "Pizza Seçimi",
18          "choiceName": "Akdeniz Pizza (Orta)",
19          "price": 0
20        },
21        {
22          "groupName": "İçecek Seçimi",
23          "choiceName": "Coca-Cola (33 cl.)",
24          "price": 0
25        }
26      ],
27      "removedIngredients": [],
28      "extras": [],
29      "itemTotal": 400.35
30    }
31  ],
32  "subtotal": 400.35,
33  "deliveryFee": 0,
34  "discount": 0,
35  "total": 400.35,
36  "deliveryAddress": {
37    "title": "Ev",
38    "address": "Atatürk Cad. No:1, Merkez/Şehir",
39    "neighborhood": "Merkez",
40    "district": "Merkez",
41    "city": "Şehir",
42    "buildingName": "Yıldız Apt.",
43    "buildingNo": "1",
44    "floor": "3",
45    "apartmentNo": "5",
46    "elevator": "var",
47    "directions": "Zili çalın",
48    "location": {
49      "type": "Point",
50      "coordinates": [
51        40.5181,
52        41.0259
53      ]
54    }
55  },
56  "customerNote": "Lütfen çatal bıçak koymayın",
57  "orderType": "delivery",
58  "scheduledFor": null,
59  "paymentMethod": "card_on_delivery",
60  "mealCardProvider": null,
61  "createdAt": "2026-04-13T11:03:47.610Z"
62}

Hata Kodları

Tüm hata yanıtları { success: false, error: "..." } formatındadır.

Kod	Durum	Açıklama
401	Unauthorized	Geçersiz veya eksik `x-webhook-secret`, veya aktif POS bağlantısı yok
400	Bad Request	Eksik veya geçersiz istek parametreleri, veya kalıcı olarak kapatılmış restoran açılmaya çalışılıyor
404	Not Found	Belirtilen sipariş veya restoran bulunamadı
429	Too Many Requests	İstek limiti aşıldı — `POST /apply` için 15 dakikada en fazla 5 başvuru

Dönebilecek Hata Mesajları

error alanında dönen metnin tamamı aşağıdadır. Bu metinler kullanıcıya gösterilebilir.

Mesaj	Kod	Ne zaman döner
x-webhook-secret header gerekli	401	Header hiç gönderilmemiş
Geçersiz webhook secret veya POS entegrasyonu durdurulmuş	401	Anahtar tanınmıyor veya firmanız pasife alınmış
Bu restoran için aktif POS bağlantısı bulunamadı	401	Restoran sizinle çalışmıyor veya bağlantı pasife alınmış
restaurantId gerekli	400	restaurantId gönderilmemiş
companyName, contactName, email, phone ve apiBaseUrl alanları zorunludur	400	`POST /apply` — zorunlu alan eksik
orderId veya posOrderId gerekli	400	`POST /webhook` — sipariş hiçbir kimlikle belirtilmemiş
isOpen alanı (true/false) zorunludur	400	`PUT /restaurant-status` — isOpen eksik veya boolean değil
Bu restoran kalıcı olarak kapatılmış. POS üzerinden açılamaz.	400	Kalıcı kapalı restoran açılmaya çalışılıyor
Sipariş bulunamadı	404	Belirtilen sipariş bu restoranda yok
Restoran bulunamadı	404	Belirtilen restoran yok
Çok fazla başvuru gönderdiniz. Lütfen daha sonra tekrar deneyin.	429	`POST /apply` — 15 dakikada 5 başvuru limiti aşıldı