POS API Dokümantasyonu

HızırYemek 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

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.

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	HızırYemek restoran ID
orderId	string	*	HızırYemek 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.

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	HızırYemek restoran ID

Yanıt Alanları

Alan	Tip	Açıklama
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	HızırYemek 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  }'

PUSHHızırYemek → POS

Yeni Sipariş Alımı

Yeni bir sipariş oluşturulduğunda HızırYemek, 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.

Payload Alanları

Alan	Tip	Açıklama
restaurantId	string	HızırYemek restoran ID
orderId	string	HızırYemek 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
total	number	Genel toplam
deliveryAddress	object	Teslimat adresi (detay aşağıda)
customerNote	string \| null	Müşteri notu (opsiyonel)
paymentMethod	string	`"online"` \| `"cash_on_delivery"` \| `"card_on_delivery"`
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

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  "total": 400.35,
35  "deliveryAddress": {
36    "title": "Ev",
37    "address": "Atatürk Cad. No:1, Merkez/Şehir",
38    "neighborhood": "Merkez",
39    "district": "Merkez",
40    "city": "Şehir",
41    "buildingName": "Yıldız Apt.",
42    "buildingNo": "1",
43    "floor": "3",
44    "apartmentNo": "5",
45    "elevator": "var",
46    "directions": "Zili çalın",
47    "location": {
48      "type": "Point",
49      "coordinates": [
50        40.5181,
51        41.0259
52      ]
53    }
54  },
55  "customerNote": "Lütfen çatal bıçak koymayın",
56  "paymentMethod": "card_on_delivery",
57  "createdAt": "2026-04-13T11:03:47.610Z"
58}

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ı