Başlangıç — FirsatGO POS Entegrasyon Geliştirici Rehberi
Model: FirsatGO 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 FirsatGO 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.
1. Üç entegrasyon yüzeyi
| Yüzey | Yön | Kim çağırır | Amaç |
|---|---|---|---|
| A | FG → POS (REST) | FirsatGO | 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 FirsatGO 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-FirsatGo-Timestampheader'ında.rawBody= gövdenin birebir ham hali (yeniden serialize etmeyin — byte-byte aynı string imzalanır).- İmza
X-FirsatGo-Signatureheader'ında, timing-safe karşılaştırılır.
Zorunlu header'lar: X-FirsatGo-Timestamp, X-FirsatGo-Signature, X-FirsatGo-Event (olay tipi),
X-FirsatGo-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-FirsatGo-Delivery-Id(ve gövdedeevent_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 (
_tsile 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-FirsatGo-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ı?)
FirsatGO 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 /ordersdüştü mü (imza geçerli,{id}döndü mü)? → Corder.preparing→ FG durumu güncellendi mi? →store.close→ FG sipariş reddediyor mu? → menü düzenle →catalog.product.upserted? - İzleme: FG outbox
delivered/failed/dead; inboxprocessed/ignored; hata →last_error.
Tam checklist: POSYOU_INTEGRATION_SPEC §9.