0. Önce bunu okuyun: kısa özet

Bu rehber, POS'unda Fırsat kuponlarını kasada kabul etmek isteyen POS firmaları (Adisyo ve diğerleri) içindir. Kod yazmaya başlamadan önce baştan sona bir kez okuyun: her adımda gerçek bir istek, gerçek bir cevap ve "ne yapmalı" notu var. Bu rehber ile OpenAPI dokümanı (GET <host>/openapi/json) çelişirse bize haber verin: sözleşme OpenAPI dokümanıdır ve bu rehber ona uymak zorundadır.

İletişim: dev@firsat.com — destek, test kimlik bilgileri, yeni test kuponları (bölüm 13).

Fırsat size bir client id, bir client secret ve POS header id'nizi (ör. adisyo/k7qm2x) verir. Id ve secret ile 1 saat geçerli bir access token alırsınız. Header id'yi token isteği dışındaki her çağrıda X-Firsat-Pos header'ı olarak gönderirsiniz.

Restoran (işletme), Fırsat Patron uygulamasından aldığı 8 karakterlik eşleştirme kodunu size verir. Bu kodu bize bir kez gönderirsiniz, karşılığında bir connection id alırsınız. Connection id'yi o restoranın kaydına saklarsınız.

Müşteri kasada bir Fırsat kuponu gösterdiğinde:

1. Önizleme: kodu bize gönderin. Kuponun ne olduğunu söyleriz: fişe eklenecek ürünler ve Fırsat'ın ödeyeceği tutar.
2. Fişe yazma: ürünleri ve indirimi POS'unuzdaki açık fişe ekleyin.
3. Onay: bize bildirin. Kuponu kullanıldı olarak işaretleriz ve bir makbuz döneriz.
4. Fişi kapatma: kasiyer Fırsat tutarını "Fırsat" adlı ödeme tipiyle kapatır: saleUnit, ya da kupon satırları fişinizde saleUnit'ten az tutuyorsa o kadarını (7.3).

Hataların çoğunu önleyen beş kural:

1. Her zaman önce önizleme, sonra fişe yazma, sonra onay. Fiş yazılmadan asla onay göndermeyin.
2. previewId başına tek Idempotency-Key. O onayın her tekrar denemesi aynı key'i ve aynı gövdeyi gönderir. Key'i ilk gönderimden önce fişle birlikte saklayın.
3. Onay timeout'a düşerse fişten hiçbir şey silmeyin. Net bir cevap alana kadar aynı isteği aynı key ile tekrar deneyin.
4. Yalnızca listelenen geçici cevaplarda tekrar deneyin (timeout, ağ hatası, 5xx, 409 POS_REDEMPTION_IN_PROGRESS, 429 ve yeni token aldıktan sonra 401). Diğer her cevapta durun ve fişi geri alın (7.6).
5. Müşterinin kendi payı için asla ödeme girmeyin. Fırsat'a özel tek ödeme "Fırsat" ödeme tipidir; tutarı min(kupon satırlarının fişteki toplamı, saleUnit) olur, asla kupon satırlarının fişte bıraktığından fazla değil.