Başlangıç — Baktin POS Entegrasyon Geliştirici Rehberi

Model: Baktin platform/talep ağıdır (Getir / Trendyol GO konumu); siz (POS/entegratör) bu sözleşmeye uyum sağlarsınız. Kanonik sözleşmeyi Baktin belirler ve sürümler. Tam alan-bazlı referans: POSYOU_INTEGRATION_SPEC.md.

Bu portal sektör-bazlıdır: önce bu sayfayı (ortak çekirdek) okuyun, sonra işletmenizin sektörüne ait sayfayı: Yemek · Market · Petshop · Çiçek · Hizmet.

0. 5 dakikada başla (Quickstart)

Sipariş çekip ürünleri senkronlamak için minimum akış. Auth: X-API-Key (FG panelinden işletme başına üretilir, daima işletme-kapsamlı).

1) Yeni siparişleri çek (keyset cursor — ilk poll since boş, sonra next_since/next_since_id'i geri ver):

curl -s "https://api.baktin.com/integration/orders?status=confirmed&limit=50" \
  -H "X-API-Key: $FG_API_KEY"
# → { "orders":[...], "next_since":"2026-06-28T...Z", "next_since_id":"...", "has_more":false }

2) Kataloğu çek (başlangıç-senkronu — ürünler + kategoriler):

curl -s "https://api.baktin.com/integration/categories" -H "X-API-Key: $FG_API_KEY"
curl -s "https://api.baktin.com/integration/products?limit=200" -H "X-API-Key: $FG_API_KEY"
# → ürün: { id, name, price, status, available, category_id, ... } + next cursor

3) Sipariş durumunu sür (POS'ta onayla/hazırla):

curl -s -X POST "https://api.baktin.com/integration/orders/$ORDER_ID/status" \
  -H "X-API-Key: $FG_API_KEY" -H "Content-Type: application/json" \
  -d '{ "action": "confirm" }'   # confirm | preparing | ready | cancel

4) Mağazayı aç/kapa & ürün durumu (opsiyonel):

curl -s -X POST "https://api.baktin.com/integration/store/status" \
  -H "X-API-Key: $FG_API_KEY" -H "Content-Type: application/json" -d '{ "is_open": false }'

curl -s -X POST "https://api.baktin.com/integration/products/$PRODUCT_ID/availability" \
  -H "X-API-Key: $FG_API_KEY" -H "Content-Type: application/json" -d '{ "is_available": false }'

Sonraki adım: Gerçek-zamanlı bildirim için webhook kur (yeni sipariş anında push). Polling yerine webhook önerilir; ikisi birlikte (webhook + periyodik gap-doldurma pull) en sağlamı. Tam referans: POSYOU_INTEGRATION_SPEC.md Bölüm B & C. Hata kodları için aynı dokümanın §1.1.

1. Üç entegrasyon yüzeyi

Yüzey	Yön	Kim çağırır	Amaç
A	FG → POS (REST)	Baktin	Sipariş gönder, katalog çek/gönder, mağaza durumu
B	POS → FG (REST)	Siz	Sipariş çek (pull/reconcile), durum sür, ürün uygunluk/fiyat
C	POS → FG (webhook)	Siz	Olay-bazlı bildirim (durum/iade/mağaza-aç-kapa/stok)

Gerçek-zamanlı çift-yön için A + C önerilir; B opsiyonel reconcile/yedektir.

2. Kimlik & güvenlik

İşletme başına Baktin panelinden iki sır üretilir:

Sır	Kullanım
`api_key`	REST kimlik: header `X-Api-Key` (A yönü) / `X-API-Key` (B yönü)
`webhook_secret`	HMAC imza (A ve C yönü)

HMAC imza şeması (A ve C):

signature = "sha256=" + HMAC_SHA256(webhook_secret, "{timestamp}.{rawBody}")

timestamp = Unix milisaniye (string), X-Baktin-Timestamp header'ında.
rawBody = gövdenin birebir ham hali (yeniden serialize etmeyin — byte-byte aynı string imzalanır).
İmza X-Baktin-Signature header'ında, timing-safe karşılaştırılır.

Zorunlu header'lar: X-Baktin-Timestamp, X-Baktin-Signature, X-Baktin-Event (olay tipi), X-Baktin-Delivery-Id (idempotency), X-Store-Id (varsa). Replay penceresi: ±5 dakika (dışı 401).

Fail-closed: Geçersiz imza/secret/zaman → 401, işlenmez. Siz de kendi tarafınızda aynı sıkılıkta doğrulayın.

3. İdempotency & güvenilirlik

İdempotency: Her olay benzersiz X-Baktin-Delivery-Id (ve gövdede event_id) taşır. Aynı kimliği iki kez İŞLEMEYİN (en-az-bir-kez teslim — tekrarlar olabilir).
Retry/backoff (FG→POS): Üstel; 6 denemede dead-letter. 2xx dönmeniz beklenir; 5xx/timeout → FG yeniden dener.
Sıra: Her durum geçişi ayrı olaydır (_ts ile sıralanır). İleri-atlanan durumda FG ara geçişleri sırayla uygular.
Tenant-izolasyon: Tüm çözümleme işletme-kapsamlıdır (IDOR-güvenli) — bir işletmenin anahtarı başka işletmeye dokunamaz.

4. Olay türleri (`X-Baktin-Event`)

Olay	Anlam
`order.created`	Yeni sipariş (tam kasa-fişi payload)
`order.updated`	Durum değişimi
`order.cancelled`	İptal (ayrı kanonik olay; `cancellation_reason` payload'da)
`refund.created` / `order.refunded`	İade → FG settlement ters-kaydı (`refund_amount(_minor)` → kısmi; yoksa tam)
`store.open` / `store.close`	Mağaza aç/kapat → FG kapalıyken yeni sipariş almaz
`catalog.product.upserted` / `stock.` / `inventory.`	Katalog/stok senkronu

POS→FG durum (inbound C): confirmed/preparing/ready/on_the_way/delivered/completed/cancelled. Siparişi FG order_id veya kendi external_order_id'nizle referanslayabilirsiniz (tenant-scoped eşleme).

5. Para birimi & finansal alanlar

TRY. Tutarlar hem major (TL, ondalıklı) hem *_minor (kuruş, tam sayı) gönderilir. Sipariş finansal değişmezi: original_subtotal − discount_amount + (delivery+service+tip+tax) = total; discount_amount = item_discount + additional_discount. Detay: POSYOU_INTEGRATION_SPEC §6.

6. Sektör farkları (neden sektör-bazlı?)

Baktin 18 sektör / 5 fulfillment-engine destekler. Ortak sözleşme (auth, finansal, durum) aynıdır; ama sipariş yaşam-döngüsü semantiği ve fulfillment{} alanları sektöre göre değişir:

Engine	Sektörler	Öne çıkan fark
food	restaurant, cafe, fast_food, bakery	Menü + malzeme modifier (eklenen/çıkarılan); preparing = mutfak
retail	market, alcohol_shop(tekel), houseware, hardware, lighting, building_materials, general_retail	SKU/barkod/stok; substitution; age_verified; preparing = toplama/paketleme
pet	petshop	retail + lot/SKT (FEFO); mama aboneliği (is_repeat)
flower	florist, flower_arrangement, event_flower	recipient/sender/card_note/delivery_slot/delivery_proof; preparing = atölye
service	field_service, professional_service, hybrid_service	Sipariş değil İŞ-EMRİ (ayrı akış); randevu-tabanlı

→ İşletmenizin sektör sayfasına geçin: sektör sayfaları.

7. Go-live

Onboarding: FG panelinden bağlantı → api_key + webhook_secret + endpoint_url + external_store_id.
Uygula: Yüzey A uçlarını yayına al + HMAC doğrula; Yüzey C webhook üreticini hazırla.
Smoke (uçtan-uca): test siparişi → A POST /orders düştü mü (imza geçerli, {id} döndü mü)? → C order.preparing → FG durumu güncellendi mi? → store.close → FG sipariş reddediyor mu? → menü düzenle → catalog.product.upserted?
İzleme: FG outbox delivered/failed/dead; inbox processed/ignored; hata → last_error.

Tam checklist: POSYOU_INTEGRATION_SPEC §9.

0. 5 dakikada başla (Quickstart)​

1. Üç entegrasyon yüzeyi​

2. Kimlik & güvenlik​

3. İdempotency & güvenilirlik​

4. Olay türleri (X-Baktin-Event)​

5. Para birimi & finansal alanlar​

6. Sektör farkları (neden sektör-bazlı?)​

7. Go-live​