Κανόνες και όρια της επιχείρησης

Όλα όσα περιγράφονται σε αυτή τη σελίδα τα ορίζει ο ιδιοκτήτης της επιχείρησης στο Προγραμματιστές → Κανόνες για τα ταμεία. Οι κανόνες ισχύουν για όλα τα κλειδιά API της επιχείρησης· ένα μεμονωμένο κλειδί (ένα ταμείο, ένα kiosk) μπορεί να έχει δικές του τιμές για οποιονδήποτε από αυτούς. Η σύνδεσή σας διαβάζει τους κανόνες που ισχύουν γι' αυτήν από το GET /v1/account, στο settings.

"settings": {
  "redemption": "hold",
  "hold_minutes": 30,
  "check_numbering": "per_register",
  "offline_max_hours": 72,
  "redeem_max_per_check": 50000,
  "redeem_max_per_day": null,
  "require_scan": true,
  "scan_window_minutes": 30,
  "allow_adjustments": false,
  "adjustment_max": 50000
}

Επίπεδα cashback

Ένα πρόγραμμα cashback μπορεί να έχει επίπεδα: για παράδειγμα Βασικό 5%, Silver 7% από τη δεύτερη επίσκεψη, Gold 10% από συνολικό ποσό 1000.00. Τα επίπεδα μετρώνται με βάση τις επισκέψεις, το συνολικό ποσό ή ό,τι από τα δύο έρθει πρώτο. Τα ορίζει ο ιδιοκτήτης στο πρόγραμμα επιβράβευσης. Από την πλευρά του ταμείου δεν χρειάζεται τίποτα: κάθε απόδειξη δίνει cashback με το επίπεδο που έχει ο πελάτης μετά από αυτή την απόδειξη, και κάθε αντικείμενο member δείχνει σε ποιο επίπεδο βρίσκεται ο πελάτης.

"cashback": {
  "balance": 10200,
  "held": 0,
  "available": 10200,
  "currency": "MDL",
  "earn_rate": 7,
  "level": "Silver",
  "level_basis": "any",
  "levels": [
    { "name": "Base", "earn_rate": 5, "min_visits": null, "min_spent": null },
    { "name": "Silver", "earn_rate": 7, "min_visits": 2, "min_spent": null },
    { "name": "Gold", "earn_rate": 10, "min_visits": null, "min_spent": 100000 }
  ],
  "next_level": { "name": "Gold", "earn_rate": 10, "visits_left": null, "spent_left": 80000 },
  ...
}

Τα next_level.visits_left και next_level.spent_left είναι έτοιμα να εμφανιστούν στον πελάτη («ακόμη 2 επισκέψεις για το Silver»). Το display.receipt_lines περιέχει ήδη αυτή τη γραμμή στη γλώσσα του πελάτη.

Κατηγορίες προϊόντων

Ανεβάστε μία φορά τα προϊόντα σας με την κατηγορία τους και μετά στέλνετε μόνο τις αλλαγές. Οι κατηγορίες εμφανίζονται στον πίνακα ελέγχου του ιδιοκτήτη, όπου για καθεμία μπορεί να οριστεί: να μη δίνει cashback (καπνός, αλκοόλ), να μην πληρώνεται με cashback (προϊόντα που είναι ήδη σε προσφορά) ή να δίνει δικό της ποσοστό αντί για το ποσοστό του επιπέδου του πελάτη (καφές 10%). Το API μπορεί να δημιουργεί προϊόντα και κατηγορίες και να τα μετονομάζει, αλλά αυτούς τους κανόνες τους αλλάζει μόνο ο ιδιοκτήτης.

curl https://loyaltyfy.io/api/v1/catalog/products/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "sku": "4840001", "name": "Marlboro Gold", "category": "TOB", "category_name": "Tobacco", "price": 6500 },
      { "sku": "1001", "name": "Latte", "category": "COF", "category_name": "Coffee", "price": 4500 },
      { "sku": "2040", "name": "Zeama", "category": "KIT", "category_name": "Kitchen", "price": 6500 }
    ]
  }'

# { "object": "catalog_sync", "upserted": 3 }

Στη συνέχεια στείλτε line_items με κάθε απόδειξη. Μια γραμμή μπορεί να έχει category ή μόνο sku: τότε βρίσκουμε την κατηγορία στον κατάλογο. Τα σύνολα των γραμμών αναπροσαρμόζονται στο ποσό της απόδειξης, ώστε οι εκπτώσεις που έγιναν στο ταμείο να κατανέμονται αναλογικά. Οι γραμμές σε κατηγορίες χωρίς κανόνες δίνουν cashback με το επίπεδο του πελάτη.

curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000130",
    "member": "2000111703779",
    "amount": 17500,
    "line_items": [
      { "sku": "4840001", "quantity": 1, "unit_price": 6500 },
      { "sku": "1001", "quantity": 1, "unit_price": 4500 },
      { "sku": "2040", "quantity": 1, "unit_price": 6500 }
    ]
  }'

# Tobacco earns nothing, Coffee has its own 10%, Kitchen earns at the guest's level (5%):
# 0 + 450 + 325 = "cashback_earned": 775

Πληρωμή με cashback μέσω δέσμευσης

Με την επιλογή Μέσα στην απόδειξη (την προεπιλογή) το ταμείο στέλνει το redeem_amount μαζί με την κλεισμένη απόδειξη. Με την επιλογή Με δέσμευση το ταμείο δεσμεύει το ποσό όταν ο πελάτης ζητά να πληρώσει με cashback, και η κλεισμένη απόδειξη το επιβεβαιώνει. Αν η απόδειξη δεν φτάσει ποτέ (έπεσε το δίκτυο, ακυρώθηκε η πώληση), η δέσμευση λύνεται μετά τον χρόνο που όρισε ο ιδιοκτήτης και τα χρήματα μένουν στον πελάτη. Καμία έκπτωση δεν δίνεται χωρίς να αφαιρεθεί από το υπόλοιπο.

1. 1
   Δέσμευση

   POST /v1/holds με το μέλος, το ποσό και το σύνολο της απόδειξης. Ισχύουν τα ίδια όρια όπως για μια απόδειξη. Η απάντηση περιέχει το id της δέσμευσης.

2. 2
   Επιβεβαίωση

   POST /v1/transactions με hold_id. Παραλείψτε το redeem_amount για να χρησιμοποιηθεί ολόκληρη η δέσμευση ή στείλτε μικρότερο ποσό.

3. 3
   Ή αποδέσμευση

   POST /v1/holds/{id}/release όταν ακυρώνεται η πώληση. Η διπλή αποδέσμευση δεν προκαλεί πρόβλημα.

curl https://loyaltyfy.io/api/v1/holds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold-R3-000131" \
  -d '{ "member": "2000111703779", "amount": 3000, "check_amount": 20000, "register_id": "R3" }'

# at payment: the check captures it
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "000131", "register_id": "R3", "member": "2000111703779",
        "amount": 20000, "hold_id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19" }'

Αριθμοί αποδείξεων ανά ταμείο

Αν κάθε ταμείο αριθμεί τις αποδείξεις από το 1, επιλέξτε Κάθε ταμείο αριθμεί τις δικές του. Τότε το register_id είναι υποχρεωτικό και αποθηκεύουμε την απόδειξη ως <register_id>:<external_id>, για παράδειγμα R3:15. Χρησιμοποιήστε αυτό το συνδυασμένο id για να διαβάσετε, να ακυρώσετε ή να κάνετε επιστροφή στην απόδειξη.

Αποδείξεις που στέλνονται αργότερα

Μετά από διακοπή το ταμείο στέλνει την ουρά του. Με όριο, ας πούμε, 72 ωρών, οι αποδείξεις με παλαιότερο closed_at απορρίπτονται με check_too_old, ώστε ένα ταμείο που επανήλθε από παλιό αντίγραφο ασφαλείας να μην πλημμυρίσει την επιχείρηση με ξεπερασμένες αποδείξεις. Ένα closed_at περισσότερο από 10 λεπτά στο μέλλον απορρίπτεται πάντα.

Όρια εξαργύρωσης

Επιπλέον του ποσοστού της απόδειξης που ορίζει το πρόγραμμα, ο ιδιοκτήτης μπορεί να ορίσει το μέγιστο cashback ανά απόδειξη και ανά πελάτη την ημέρα (για όλα τα ταμεία μαζί, με τη ζώνη ώρας της επιχείρησης). Μια απόδειξη που ζητά περισσότερα εξαργυρώνει όσο επιτρέπεται και η απάντηση δείχνει το πραγματικό redeem_amount· μια δέσμευση που ζητά περισσότερα απορρίπτεται με limited_by. Χρησιμοποιήστε τον υπολογισμό για να δείξετε πρώτα στον πελάτη το ακριβές ποσό.

Υποχρεωτική σάρωση κάρτας

Με αυτόν τον κανόνα μια απόδειξη, επίσκεψη, δέσμευση ή επιβράβευση για μια κάρτα γίνεται δεκτή μόνο αν το ίδιο κλειδί έστειλε αυτή την κάρτα στο POST /v1/scans λίγο πριν. Ένας αριθμός κάρτας που πληκτρολογήθηκε με το χέρι στο ταμείο απορρίπτεται με scan_required. Στείλτε την ακατέργαστη έξοδο του σαρωτή στο /v1/scans και συνεχίστε κανονικά.

Χειροκίνητες διορθώσεις

Είναι απενεργοποιημένες από προεπιλογή. Όταν τις επιτρέψει ο ιδιοκτήτης, ένα κλειδί με το δικαίωμα members:adjust μπορεί να προσθέσει ή να αφαιρέσει cashback με αιτιολογία, έως το όριο ανά διόρθωση που όρισε ο ιδιοκτήτης. Κάθε διόρθωση καταγράφεται στο ιστορικό του μέλους και στέλνει balance.adjusted.

curl https://loyaltyfy.io/api/v1/members/2000111703779/adjustments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "ADJ-2026-0009", "amount": 2000, "reason": "Goodwill after a complaint" }'

# a negative amount takes cashback away