FirsatGO POS Entegrasyonu — Çiçek (Flower) Sektörü Developer Dokümanı

Engine: flower · Sektörler: florist, flower_arrangement, event_flower Para birimi: TRY · Tüm tutarlar major (TL, ondalıklı) + *_minor (kuruş, tam sayı) ikili gönderilir.

Genel Bakış

Çiçek sektörü, gönderen ile alıcının farklı kişiler olduğu ve teslimatın çoğunlukla planlı bir zaman aralığında (slot) yapıldığı bir akıştır. Sipariş, atölyede (workroom) aranjman olarak hazırlanır, teslim slotu beklenir, rotaya çıkar ve teslimat fotoğraf/imza kanıtı ile kapatılır. Bu nedenle ortak sipariş sözleşmesine ek olarak fulfillment{} altında alıcı/gönderen ayrımı, kart mesajı, teslim slotu, muadil (substitution) politikası ve teslim kanıtı alanları taşınır.

Sipariş Yaşam-Döngüsü

Çiçek state-machine'i (engine=flower):

Durum	Anlam
`pending`	Sipariş oluştu, henüz onaylanmadı.
`confirmed`	İşletme/POS siparişi onayladı.
`preparing`	Atölyede (WORKROOM) aranjman hazırlığı sürüyor.
`ready`	Aranjman hazır, teslim SLOT'u (`delivery_slot`) bekleniyor.
`on_the_way`	Kurye ROTAda, alıcıya gidiyor.
`delivered`	Teslim edildi; `delivery_proof` (foto/imza) bu adımda zorunludur.
`completed`	Sipariş kapandı.

İptal akışı ayrı kanonik olaydır: order.cancelled (cancellation_reason ile). İade refund.created / order.refunded (settlement ters-kayıt; refund_amount / refund_amount_minor ile kısmi olabilir).

Inbound durum eşleştirmesi (POS→FG): confirmed, preparing, ready, on_the_way, delivered, completed, cancelled — sipariş order_id veya external_order_id ile referanslanır.

Sektöre-Özel Sipariş Alanları

Aşağıdaki alanlar yalnız çiçek sektöründe fulfillment{} altında taşınır. Ortak finansal/müşteri/adres alanları (bkz. ortak sözleşme) burada tekrarlanmaz.

`fulfillment{}` (flower)

Alan	Tip	Anlam
`recipient.name`	string	Alıcının adı (sipariş verenden farklı olabilir).
`recipient.phone`	string	Alıcı telefonu.
`recipient.address`	string	Alıcı teslim adresi.
`recipient.district`	string	Alıcı ilçesi.
`sender.name`	string	Gönderen adı.
`sender.phone`	string	Gönderen telefonu.
`sender.anonymous`	boolean	`true` ise gönderen alıcıya anonim kalır.
`card_note`	string	Çiçekle iletilecek kart mesajı.
`delivery_slot.date`	string (date)	Planlı teslim tarihi.
`delivery_slot.window`	string	Teslim zaman-aralığı (ör. "14:00-16:00").
`substitution_policy`	string	Çiçek mevcut değilse muadil (substitution) kuralı.
`delivery_proof.photo`	string	Teslim kanıtı fotoğrafı.
`delivery_proof.signature`	string	Teslim imzası.
`delivery_proof.recipient_name`	string	Teslim alanın adı.
`delivery_proof.at`	string (datetime)	Teslim zamanı.

scheduled_for (ortak alan) planlı teslim için kullanılır; delivery_slot bunu tarih + pencere olarak detaylandırır. delivery_directions ve delivery_address.directions (ortak alan) adres tarifi için kullanılabilir.

`items[]`

Her satırda aranjman (arrangement) maliyeti olabilir. Diğer satır alanları ortak sözleşmeye uyar (per-line original_subtotal / item_discount vb.).

Katalog / Ürün

Ürün şekli ortak katalog sözleşmesini izler:

FG→POS upsert: POST {posBase}/catalog/products
Çekme: GET {posBase}/catalog/categories, GET {posBase}/catalog/products
Stok/fiyat güncelleme (POS→FG): products/:id/availability + products/:id/price
Katalog olayları: catalog.product.upserted, stock.*, inventory.*

Çiçek sektörüne özel ürün notu: bir ürün aranjman (arrangement) kalemi olarak fiyatlandırılabilir; aranjman maliyeti sipariş satırına yansır.

Akış Notları

Alıcı ≠ gönderen: Teslimat fulfillment.recipient adresine yapılır; customer / delivery_address sipariş vereni temsil edebilir. Kurye/operasyon ekranlarında alıcı bilgisi esas alınmalıdır.
Anonim gönderim: sender.anonymous=true ise gönderenin kimliği alıcıya gösterilmez; yalnız card_note iletilir.
Slot disiplini: ready durumu teslim slotunu bekler; delivery_slot.window dışında rotaya çıkma (on_the_way) operasyonel hatadır.
Muadil ürün: Stokta olmayan çiçek için substitution_policy uygulanır; muadil ürün kararı bu politikaya bağlıdır.
Teslim kanıtı zorunlu: delivered durumuna geçişte delivery_proof (foto ve/veya imza + recipient_name + at) gönderilmelidir.
İdempotency & güvenlik: Webhook'larda X-FirsatGo-Delivery-Id/event_id tekrar işlenmez, HMAC imza "sha256="+HMAC_SHA256(webhook_secret,"{timestamp_ms}.{rawBody}"), ±5dk replay penceresi, geçersiz imza→401 (fail-closed). Retry 6 deneme → dead-letter. Kill-switch: INTEGRATION_LIVE_DISPATCH.

Örnek

POST {posBase}/orders gövdesi (çiçek alanlarıyla):

{
  "order_id": "fg_ord_9F2C7A",
  "order_number": "FG-2026-104377",
  "status": "confirmed",
  "type": "delivery",
  "original_subtotal": 850.00,
  "original_subtotal_minor": 85000,
  "item_discount": 0.00,
  "item_discount_minor": 0,
  "additional_discount": 50.00,
  "additional_discount_minor": 5000,
  "discount_amount": 50.00,            // item_discount + additional_discount
  "discount_amount_minor": 5000,
  "coupon_code": "ANNELER10",
  "tax": 0.00,
  "tax_minor": 0,
  "delivery_fee": 60.00,
  "delivery_fee_minor": 6000,
  "service_fee": 0.00,
  "service_fee_minor": 0,
  "tip_amount": 0.00,
  "tip_amount_minor": 0,
  "total": 860.00,
  "total_minor": 86000,
  "payment_method": "online",
  "payment_method_label": "Online Kredi Kartı",
  "customer": {
    "user_id": "usr_5521",
    "name": "Burak Ergün",
    "phone": "+905551112233"
  },
  "delivery_address": {
    "street": "Bağdat Cad. No:120",
    "city": "İstanbul",
    "district": "Kadıköy",
    "directions": "Apartman girişi sağda",
    "name": "Burak Ergün",
    "phone": "+905551112233",
    "coordinates": { "lat": 40.9785, "lng": 29.0560 }
  },
  "delivery_directions": "Zili Demir ailesine çalın",
  "notes": "Kırmızı güller tercih edilir",
  "scheduled_for": "2026-06-29T14:00:00+03:00",
  "estimated_time": 90,
  "items": [
    {
      "name": "40'lı Kırmızı Gül Aranjmanı",
      "quantity": 1,
      "arrangement": true,
      "original_subtotal": 850.00,
      "original_subtotal_minor": 85000
    }
  ],
  "fulfillment": {
    "recipient": {
      "name": "Elif Demir",
      "phone": "+905559998877",
      "address": "Caferağa Mah. Moda Cad. No:14 D:3",
      "district": "Kadıköy"
    },
    "sender": {
      "name": "Burak Ergün",
      "phone": "+905551112233",
      "anonymous": false
    },
    "card_note": "Doğum günün kutlu olsun! Sevgiyle.",
    "delivery_slot": {
      "date": "2026-06-29",
      "window": "14:00-16:00"
    },
    "substitution_policy": "Kırmızı gül yoksa eşdeğer kırmızı çiçekle değiştir",
    "delivery_proof": {
      "photo": null,
      "signature": null,
      "recipient_name": null,
      "at": null
    }
  },
  "created_at": "2026-06-28T10:12:00+03:00",
  "updated_at": "2026-06-28T10:14:00+03:00"
}

delivered durumuna geçişte (POS→FG, order.updated) delivery_proof doldurulur:

{
  "order_id": "fg_ord_9F2C7A",
  "status": "delivered",
  "fulfillment": {
    "delivery_proof": {
      "photo": "https://cdn.firsatgo.com/proof/9F2C7A.jpg",
      "signature": "https://cdn.firsatgo.com/sign/9F2C7A.png",
      "recipient_name": "Elif Demir",
      "at": "2026-06-29T15:22:00+03:00"
    }
  }
}

Genel Bakış​

Sipariş Yaşam-Döngüsü​

Sektöre-Özel Sipariş Alanları​

fulfillment{} (flower)​

items[]​

Katalog / Ürün​

Akış Notları​

Örnek​