StokPlus+ POS & E-Belge Webhook API

Sürüm 1.0 · Haziran 2026 · POS yazılımı & entegratör firmalar için resmi spesifikasyon

1. Amaç

POS veya middleware sisteminiz, satış tamamlandığında bu API'ye HTTP POST atar. StokPlus+ sunucusu envanter stoklarını otomatik düşer. POS tarafında stok hesaplaması gerekmez.

Tek entegrasyon kapısı — Simpra, Adisyo, NarPOS, SambaPOS veya özel POS; hepsi aynı JSON şemasını kullanır.

2. Uç noktalar

URL	Metod	Kullanım
https://us-central1-stok-takip-6f8e9.cloudfunctions.net/posWebhook	POST	Genel Bulut POS satışı
https://us-central1-stok-takip-6f8e9.cloudfunctions.net/sambaposSale	POST	SambaPOS uyumlu alias
https://us-central1-stok-takip-6f8e9.cloudfunctions.net/eBelgeWebhook	POST	E-Fatura / E-Arşiv alış → stok girişi
https://us-central1-stok-takip-6f8e9.cloudfunctions.net/integrationInfo	GET	Uç nokta listesi (health check)

3. Kimlik doğrulama

Parametre	Nerede	Zorunlu
`businessId`	JSON gövdesi	Evet
`x-api-key`	HTTP başlığı (`sk_…`)	Evet

Değerler: StokPlus+ Web Panel → Ayarlar → Entegrasyon Merkezi (işletme sahibi).

4. POS satış isteği

Örnek istek

POST /posWebhook HTTP/1.1
Content-Type: application/json
x-api-key: sk_ORNEK_ANAHTAR

{
  "businessId": "ABC123",
  "ticketId": "FIS-2026-004821",
  "kaynak": "partner_pos",
  "kalemler": [
    {
      "barkod": "8690123456789",
      "urunAdi": "Americano",
      "miktar": 2,
      "fiyat": 89.90
    }
  ]
}

Alanlar

Alan	Tür	Zorunlu	Açıklama
`businessId`	string	Evet	İşletme kodu
`ticketId`	string	Önerilir	Fiş ID — tekrar gönderimde aynı kalır (idempotency)
`kaynak`	string	Hayır	POS etiketi: simpra, adisyo, narpos…
`kalemler[]`	array	Evet*	Satış satırları
`kalemler[].barkod`	string	**	1. eşleştirme önceliği
`kalemler[].urunAdi` / `ad`	string	**	2. eşleştirme (tam ad, case-insensitive)
`kalemler[].miktar`	number	Evet	Satılan adet (> 0)
`kalemler[].fiyat`	number	Hayır	Raporlama için birim fiyat

* Tek kalem için kök seviyede barkod, urunAdi, miktar de kabul edilir.
** Her kalemde barkod veya ürün adı zorunludur.

Başarılı yanıt (200)

{
  "ok": true,
  "processed": 1,
  "ticketId": "FIS-2026-004821",
  "message": "Satış kuyruğa alındı — stok otomatik güncellenecek"
}

Hata kodları

HTTP	Anlam
400	Eksik/hatalı gövde
401	Geçersiz API anahtarı veya entegrasyon kapalı
404	İşletme bulunamadı
405	Yalnızca POST
500	Sunucu hatası — exponential backoff ile retry

5. Tetikleme zamanı

Gönderin: Ödeme tamamlandı / fiş kapatıldı.

Göndermeyin: Taslak fiş, sepet, masa açma.

[POS: ödeme OK] → [kalemleri normalize et] → [POST posWebhook] → 200: kabul edildi → StokPlus+ stok düşer (async)

6. Idempotency

Aynı ticketId ile retry güvenlidir. Daha önce işlenmiş satırlar atlanır; çift stok düşümü oluşmaz.

7. E-Belge (alış) webhook'u

POST /eBelgeWebhook
x-api-key: sk_ORNEK_ANAHTAR

{
  "businessId": "ABC123",
  "belgeNo": "GIB2026000001234",
  "tip": "E_FATURA",
  "tedarikci": "Tedarikçi A.Ş.",
  "kalemler": [
    { "barkod": "8690123456789", "ad": "Un 25kg", "miktar": 10, "fiyat": 250 }
  ]
}

tip: E_FATURA · E_ARSIV · E_IRSALIYE — stok artar.

8. cURL test

curl -X POST "https://us-central1-stok-takip-6f8e9.cloudfunctions.net/posWebhook" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_ORNEK_ANAHTAR" \
  -d '{"businessId":"ABC123","ticketId":"TEST-001","kalemler":[{"barkod":"8690123456789","urunAdi":"Test","miktar":1,"fiyat":49.9}]}'

9. JSON Schema

Makine okunabilir şemalar (GitHub repo):

integrations/pos-webhook/schema.pos-sale.json
integrations/pos-webhook/schema.e-belge.json

10. Ortaklık & destek

Entegrasyon ortaklığı ve teknik sorular: entegrasyon@aevumstudios.com.tr

Cloud Functions canlı ortam için Firebase Blaze planı gereklidir. Webhook'lar deploy sonrası aktif olur.