POS Entegrasyon Rehberi

Bu rehber, herhangi bir POS/adisyon sisteminin Restomarkt'a nasıl bağlanacağını uçtan uca anlatır. Entegrasyon tamamlandığında restoran, POS'unda satış yaptıkça malzeme stoğu Restomarkt'ta güncellenir; kritik eşiğin altına inen malzemeler için tedarikçisine otomatik cari siparişaçılır ve sipariş teslim edildiğinde POS'unuz webhook ile haberdar olur. Restomenüm bu akışın hazır bir uygulamasıdır — aynı uçlar tüm POS'lara açıktır.

POS satış yapar ──► POST /stock (delta veya mutlak seviye)
                        │
                        ▼
        Restomarkt stok kalemini günceller
                        │  (eşik ÜSTÜNDEN ALTINA geçiş + mod=otomatik)
                        ▼
        Tedarikçiye cari sipariş otomatik açılır ──► order.created webhook'u
                        │
                        ▼
        Tedarikçi hazırlar / sevk eder / teslim eder ──► order.status_changed webhook'ları
                        │
                        ▼
POS "delivered" olayında gelen malı stoğuna ekler (döngü kapanır)

Ön koşullar

Restoranın Restomarkt hesabı ve panelden üretilmiş bir restoran API anahtarı (/restoran/api).
Anahtarda şu yetkiler: stock:read, stock:write, orders:read ve (webhook için) webhooks:manage.
Webhook alacaksanız HTTPS ile erişilebilir bir uç.

Kurulum adımları

1Anahtarı doğrulayın

İlk çağrı olarak GET /me ile anahtarın restoran anahtarı olduğunu ve yetkilerini kontrol edin.

curl https://restomarkt.com/api/v1/me -H "Authorization: Bearer rmk_live_..."
// { "owner_type": "restaurant", "owner_name": "...", "scopes": ["stock:read", "stock:write", ...] }

2Malzemeleri gönderin — iki mod

Mutlak mod (stock):POS'unuz malzeme bazında stok tutuyorsa (reçete/envanter modülü varsa) güncel seviyeleri gönderin. Aynı malzeme adı aynı kaleme yazılır; ad eşleşmesi Türkçe karakter ve büyük/küçük duyarsızdır.

Delta modu (delta):POS'unuz yalnızca satışı biliyorsa, satış anında düşümü gönderin (örn. 2 pizza satıldı → hamur için delta: -2). Reçete çarpanını (1 pizza = kaç birim malzeme) POS tarafında uygulayın. Mal kabulünde pozitif delta gönderebilirsiniz. Sonuç 0'ın altına inmez.

curl -X POST https://restomarkt.com/api/v1/stock \
  -H "Authorization: Bearer rmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"ingredient":"Pizza Hamuru","delta":-2},
    {"ingredient":"Mozzarella","stock":7.5}
  ]}'
// { "updated": 2, "created_orders": [] }

Tek istekte en fazla 500 kalem gönderilebilir. Bilinmeyen malzeme adı hata değildir: otomatik taslak kalem oluşturulur ve panelde eşlenmeyi bekler.

3Eşleme durumunu izleyin

Malzeme → Restomarkt ürünü eşlemesini restoran panelde yapar (hangi tedarikçinin hangi ürünü sipariş edilecek). Entegrasyonunuz GET /stock?mapped=falseile eşlenmemiş kalemleri görüp kullanıcıyı panele yönlendirebilir — iyi bir entegrasyon kurulum ekranında "3 malzeme eşlenmemiş" uyarısı gösterir.

curl "https://restomarkt.com/api/v1/stock?mapped=false" -H "Authorization: Bearer rmk_live_..."
// { "items": [...], "meta": { "limit": 50, "offset": 0, "total": 3, "unmapped": 3 } }

4Otomatik siparişin kurallarını bilin

Otomatik sipariş şu koşulların TAMAMI sağlanınca açılır:

Restoran panelde sipariş modunu otomatik seçmiş (varsayılan: manuel öneri).
Kalem bir ürüne eşlenmiş ve sipariş miktarı (reorder_qty) 0'dan büyük.
Stok, eşiğin üstünden altına geçti — sürekli eşik altında kalan kalem her bildirimde tekrar sipariş açmaz.
Aynı kalem için son otomatik siparişin üzerinden 6 saat geçmiş (bekleme süresi).

Açılan siparişlerin kimlikleri POST /stock yanıtındaki created_orders dizisinde döner; detayını GET /orders/:id ile çekebilirsiniz. Ödeme yöntemi caridir (online ödeme otomatik açılmaz).

5Webhook kurun ve test edin

Sipariş oluşumunu ve durum değişikliklerini (onay, sevkiyat, teslim) polling yapmadan almak için webhook kaydedin, ardından test olayıyla ucunuzu doğrulayın:

curl -X POST https://restomarkt.com/api/v1/webhooks \
  -H "Authorization: Bearer rmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pos-ornek.com/restomarkt-webhook"}'
// { "webhook": { "id": "...", "secret": "whsec_..." } }  ← secret'ı saklayın

curl -X POST https://restomarkt.com/api/v1/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer rmk_live_..."
// { "delivered": true, "status_code": 200 }

İmza doğrulama, teslimat gövdesi ve retry politikası (2dk → 10dk → 30dk → 2sa, 5 deneme) için Webhook'lar sayfasına bakın. Olaylar en az bir kez teslim edilir — X-Restomarkt-Delivery-Id başlığıyla tekilleştirin.

6Döngüyü kapatın: teslimatta stok girişi

order.status_changed olayında status = "delivered" gördüğünüzde GET /orders/:id ile kalemleri çekin ve gelen miktarları POS stoğunuza ekleyin (veya pozitif deltaile Restomarkt'a geri bildirin). Böylece stok her iki sistemde de doğru kalır.

Sık sorulanlar

Hangi sıklıkta göndermeliyim?Delta modunda satış anında (veya 1-5 dk'lık toplu paketlerle), mutlak modda gün içinde birkaç senkron yeterlidir. Hız sınırı anahtar başına dakikada 120 istektir; kalemler tek istekte toplanabildiği için pratikte sınıra takılmazsınız.

Aynı bildirimi yanlışlıkla iki kez gönderirsem? Mutlak mod doğal olarak idempotenttir (aynı seviye tekrar yazılır). Delta modunda tekrar gönderim çift düşüm yapar — ağ hatasında tekrar deneyecekseniz gönderim kuyruğunuzu kalem bazında işaretleyin. Otomatik sipariş tarafı korumalıdır: eşik geçişi + 6 saat bekleme kuralı, tekrarlanan bildirimlerin sipariş yağmuruna dönmesini engeller.

Malzeme adları POS'ta değişirse? Yeni ad yeni bir taslak kalem oluşturur; panelden yeni kalemi ürüne eşlemek yeterlidir. Eski kalem senkron almadığı için pasif kalır.

Şubeli restoranlar? API anahtarı restoran hesabına bağlıdır; otomatik siparişler varsayılan/ilk şubeye açılır. Şube bazlı stok akışı için şube başına ayrı Restomarkt hesabı kullanın veya bize yazın.

Makine okunur sözleşme: GET /api/v1/openapi.json. Entegrasyonunuzu listelemek veya teknik destek için iletişime geçin.