☰ Μενού · Κανόνες και όρια της επιχείρησης
Οδηγοί

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

Πώς η επιχείρηση ελέγχει τι επιτρέπεται στα συνδεδεμένα ταμεία: επίπεδα cashback, κατηγορίες προϊόντων, δεσμεύσεις, αρίθμηση αποδείξεων, καθυστερημένες αποδείξεις, όρια και έλεγχος σάρωσης.

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

JSON
"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,
  "card_prefix": "2999"
}

Επίπεδα cashback

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

JSON
"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
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 με το επίπεδο του πελάτη. Κάθε συναλλαγή και το POST /v1/checks/calculate επιστρέφουν line_items με όσα κέρδισε κάθε γραμμή, και μια επιστροφή μπορεί να ονομάσει τις γραμμές που επιστράφηκαν. Ο ιδιοκτήτης μπορεί επίσης να παρακάμψει τον κανόνα μιας κατηγορίας σε ένα μόνο προϊόν, μόνιμα ή μόνο μεταξύ δύο ημερομηνιών (προσφορά).

curl
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

Στα καταστήματα με ενεργή τη λεπτομερή σειρά κανόνων, το category μπορεί να είναι και το όνομα της κατηγορίας όπως το βλέπει ο ιδιοκτήτης στον κατάλογο («Μπίρα», όχι μόνο «106», χωρίς διάκριση πεζών κεφαλαίων): η γραμμή ακολουθεί τότε τους κανόνες αυτής της κατηγορίας. Το όνομα μιας κατηγορίας δεν δημιουργεί ποτέ νέα κατηγορία. Μια τιμή που ο κατάλογος δεν γνωρίζει αντικαθίσταται από την κατηγορία του προϊόντος με βάση το sku· μόνο αν το προϊόν δεν έχει κατηγορία, η τιμή εμφανίζεται ως νέα κατηγορία. Κερδίζει ο πιο συγκεκριμένος κανόνας: το προϊόν, μετά η κατηγορία του, μετά το πρόγραμμα ή το επίπεδο· ένα προϊόν με δικό του ποσοστό το παίρνει ακόμη και σε κατηγορία χωρίς συσσώρευση. Σε απόδειξη κάτω από το ελάχιστο ποσό του προγράμματος, ή σε τοποθεσία χωρίς συσσώρευση, κάθε γραμμή απαντά earn_percent: null και cashback_earned: 0, και κάτω από το ελάχιστο η απόδειξη απαντά earn_rate: 0.

Πληρωμή με 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
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" }'
Οι δεσμεύσεις λαμβάνονται υπόψη παντού: στο cashback.available του μέλους, στα όρια και στην εφαρμογή ταμείου της ίδιας της επιχείρησης, ώστε τα ίδια χρήματα να μην ξοδευτούν δύο φορές.

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

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

Πρόθεμα αριθμού κάρτας

Οι κάρτες που εκδίδουμε παίρνουν αριθμό 13 ψηφίων. Αν το ταμείο αναγνωρίζει τις κάρτες πιστότητας από τα πρώτα ψηφία, ορίστε πρόθεμα στο Προγραμματιστές → Κανόνες για τα ταμεία: οι νέες κάρτες θα αρχίζουν με αυτό. Τα ψηφία μένουν μέσα στους 13 χαρακτήρες (το πρόθεμα 2999 δίνει 2999 και 9 ακόμη ψηφία), τα γράμματα μπαίνουν μπροστά. Οι κάρτες που έχουν ήδη εκδοθεί κρατούν τους αριθμούς τους, και ένα card_number που στέλνεται με POST /v1/members υπερισχύει πάντα. Το πρόθεμα επιστρέφεται στο settings.card_prefix του GET /v1/account.

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

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

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

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

Κανόνες ανά κατάστημα

Ο ιδιοκτήτης συνδέει τους κωδικούς ταμείων με ένα κατάστημα στην ενότητα Καταστήματα. Ο κωδικός είναι το register_id που στέλνει το ταμείο με αποδείξεις, υπολογισμούς και δεσμεύσεις. Ένα κατάστημα μπορεί να απενεργοποιήσει τη συσσώρευση, να έχει δικό του ποσοστό, να απαγορεύσει την πληρωμή με cashback ή να έχει δικό του μέρος της απόδειξης που πληρώνεται με cashback. Ο ιδιοκτήτης επιλέγει επίσης τι υπερισχύει όταν προϊόν (κατηγορία), κατάστημα και επίπεδο πελάτη έχουν το καθένα ποσοστό: προϊόν, κατάστημα, επίπεδο· κατάστημα, προϊόν, επίπεδο· ή το επίπεδο του πελάτη πριν από το κατάστημα (τότε το ποσοστό του καταστήματος αντικαθιστά μόνο το βασικό επίπεδο). Μια κατηγορία χωρίς συσσώρευση μένει εξαιρεμένη σε κάθε σειρά. Όπου δεν επιτρέπεται η πληρωμή με cashback, το POST /v1/checks/calculate απαντά max_redeem: 0 με redeem_blocked_reason και μια απόδειξη ή δέσμευση με cashback απορρίπτεται με 400 redeem_not_allowed_here. Απόδειξη χωρίς register_id ή με κωδικό που δεν συνδέεται με κατάστημα ακολουθεί τους γενικούς κανόνες· οι άγνωστοι κωδικοί εμφανίζονται σε λίστα για σύνδεση.

Σειρά κανόνων

Αν η επιχείρηση χρησιμοποιεί εξαιρέσεις ανά κατάστημα, κάθε γραμμή της απόδειξης ακολουθεί τον πιο συγκεκριμένο κανόνα: την εξαίρεση του καταστήματος για το προϊόν, μετά την εξαίρεση του καταστήματος για την κατηγορία, μετά τον κανόνα του προϊόντος, της κατηγορίας, το δικό ποσοστό του καταστήματος και τέλος το επίπεδο του πελάτη ή το ποσοστό του προγράμματος. Κάθε πεδίο (ποσοστό, συλλογή, πληρωμή με cashback) λαμβάνεται από τον πρώτο κανόνα που το ορίζει. Παράδειγμα: πρόγραμμα 5%, κατηγορία Αλκοόλ 3%, στο κατάστημα Ciocana για Αλκοόλ 2%. Στο Ciocana μια γραμμή αλκοόλ παίρνει 2%, στα άλλα καταστήματα 3%, τα υπόλοιπα προϊόντα 5%. Οι εξαιρέσεις ισχύουν μόνο για αποδείξεις με register_id συνδεδεμένο με κατάστημα. Η απενεργοποιημένη συλλογή ή εξαργύρωση σε κατάστημα και το όριο εξαργύρωσης του καταστήματος ισχύουν πάντα. Διαβάστε τις εξαιρέσεις με GET /v1/catalog/location-rules.

Cashback ως πληρωμή ή ως έκπτωση

Ο λογιστής του καταστήματος επιλέγει στο Προγραμματιστές → Κανόνες ταμείων πώς καταχωρεί το ταμείο την πληρωμή με cashback. Ως πληρωμή (προεπιλογή): το cashback είναι τρόπος πληρωμής, ένα ποσό δίπλα σε μετρητά και κάρτα· οι τιμές και ο ΦΠΑ δεν αλλάζουν. Ως έκπτωση: το cashback μειώνει τις τιμές των προϊόντων και ο ΦΠΑ υπολογίζεται στην τιμή μετά την έκπτωση. Σε αυτή τη λειτουργία κάθε γραμμή του POST /v1/checks/calculate και του POST /v1/transactions έχει επίσης redeem_allocated (μικρότερες μονάδες): το μέρος του redeem_amount που αντιστοιχεί στη γραμμή, αναλογικά με το ποσό της. Οι γραμμές που δεν πληρώνονται με cashback παίρνουν 0 και οι γραμμές αθροίζουν πάντα ακριβώς redeem_amount (τα λεπτά που περισσεύουν πάνε στη μεγαλύτερη γραμμή). Η λειτουργία βρίσκεται στο settings.redeem_accounting του GET /v1/account (payment ή discount). Χωρίς line_items δεν γίνεται κατανομή.

JSON
{
  "amount": 10000,
  "redeem_amount": 1000,
  "net_amount": 9000,
  "line_items": [
    { "sku": "LATTE", "amount": 6000, "redeemable": true, "redeem_allocated": 600 },
    { "sku": "CAKE", "amount": 3000, "redeemable": true, "redeem_allocated": 300 },
    { "sku": "WATER", "amount": 1000, "redeemable": true, "redeem_allocated": 100 }
  ]
}

Τύποι έκπτωσης

Στείλτε την έκπτωση που έκανε το ταμείο στο discount_type, έναν κωδικό έως 64 χαρακτήρες όπως employee, discount_card ή promo, σε όλη την απόδειξη και, αν χρειάζεται, σε μεμονωμένες γραμμές (line_items[].discount_type). Κάθε νέος κωδικός εμφανίζεται μόνος του στο Για προγραμματιστές → Τύποι έκπτωσης, όπου ο ιδιοκτήτης του δίνει όνομα και αποφασίζει αν μια τέτοια απόδειξη κερδίζει cashback και αν πληρώνεται με cashback. Ένας νέος τύπος κερδίζει και επιτρέπει πληρωμή μέχρι να τον αλλάξει ο ιδιοκτήτης. Τύπος απόδειξης χωρίς κέρδος δίνει 0 cashback σε όλη την απόδειξη· τύπος γραμμής χωρίς κέρδος δίνει 0 μόνο σε εκείνη τη γραμμή. Όπου η πληρωμή με cashback δεν επιτρέπεται, το POST /v1/checks/calculate απαντά max_redeem: 0 με limited_by: "discount_type" και redeem_blocked_reason: "discount_redeem_not_allowed", και το POST /v1/transactions με redeem_amount ή hold_id απορρίπτεται με 400 discount_redeem_not_allowed. Οι απαντήσεις τότε έχουν και discount_type (ο τύπος και οι κανόνες του) και κάθε γραμμή το δικό της discount_type. Καταστήματα χωρίς τύπους έκπτωσης μπορούν να στέλνουν το πεδίο: αγνοείται.

Προϊόντα σε προσφορά

Σημειώστε μια γραμμή της απόδειξης ως προϊόν σε προσφορά με line_items[].promo: true στα POST /v1/checks/calculate, POST /v1/transactions και POST /v1/holds. Ο ιδιοκτήτης ορίζει δύο κανόνες για τέτοιες γραμμές στο Προγραμματιστές → Κανόνες ταμείων → Προϊόντα σε προσφορά: συγκέντρωση cashback (ενεργό από προεπιλογή) και πληρωμή με cashback (ανενεργό από προεπιλογή). Ένας ανενεργός κανόνας υπερισχύει κάθε κανόνα προϊόντος, κατηγορίας και καταστήματος για αυτή τη γραμμή: η γραμμή δεν δίνει τίποτα (earn_percent: null, cashback_earned: 0) ή δεν πληρώνεται με cashback (redeemable: false). Ένας ενεργός κανόνας δεν αλλάζει τίποτα, η γραμμή ακολουθεί τους συνήθεις κανόνες της. Το μέρος της απόδειξης που πληρώνεται με cashback, το max_redeem και, με εξαργύρωση ως έκπτωση, το redeem_allocated αφήνουν έξω τις γραμμές σε προσφορά, οπότε μοιράστε το cashback μόνο στις γραμμές με redeemable: true. Κάθε γραμμή της απάντησης φέρει τότε promo (true ή false), η απόδειξη το αποθηκεύει και το GET /v1/account επιστρέφει τους κανόνες στα settings.promo_earn και settings.promo_redeem. Τιμή άλλη από true, false ή null απαντά 400 parameter_invalid. Μια επιστροφή ακολουθεί ό,τι έκανε η αρχική γραμμή, οπότε εκεί το promo δεν χρειάζεται. Καταστήματα χωρίς αυτόν τον κανόνα μπορούν να στέλνουν το πεδίο: αγνοείται.

Αίτημα · POST /v1/checks/calculate
{
  "member": "2000111703779",
  "amount": 10000,
  "line_items": [
    { "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "promo": true },
    { "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 3000 }
  ]
}
Απάντηση · 200 (απόσπασμα): πληρωμή με cashback ανενεργή
{
  "object": "check_calculation",
  "amount": 10000,
  "max_redeem": 900,
  "cashback_earned": 500,
  "earn_rate": 5,
  "line_items": [
    { "sku": "4840001", "amount": 7000, "earn_percent": 5, "cashback_earned": 350, "redeemable": false, "promo": true },
    { "sku": "2040", "amount": 3000, "earn_percent": 5, "cashback_earned": 150, "redeemable": true, "promo": false }
  ],
  ...
}

Δώρα που περιμένουν παράδοση

Ο ιδιοκτήτης ορίζει τους κανόνες στη σελίδα Δώρα: ένα δώρο για το σύνολο αγορών (για παράδειγμα 5000 MDL, ένα μπουκάλι κρασί) ή για την άνοδο σε επίπεδο cashback. Όταν μια απόδειξη περνά το όριο ή ανεβάζει τον πελάτη σε αυτό το επίπεδο, το δώρο ανοίγει και περιμένει τον πελάτη. Κάθε πελάτης παίρνει ένα δώρο ανά κανόνα, μία φορά· πολλά όρια που περνά μία απόδειξη ανοίγουν πολλά δώρα. Πελάτες που είχαν περάσει το όριο πριν ενεργοποιηθεί ο κανόνας δεν παίρνουν τίποτα, και μια επιστροφή δεν παίρνει πίσω το δώρο. Ένα δώρο μπορεί να έχει προθεσμία· μετά είναι expired.

Ροή για το ταμείο: 1) Το POST /v1/checks/calculate απαντά gifts.pending (ήδη σε αναμονή) και gifts.unlocks (ό,τι θα ανοίξει αυτή η απόδειξη, με id: null), και η πρώτη γραμμή του display.cashier_text είναι το δώρο· δείξτε τη στον ταμία. 2) Το POST /v1/transactions απαντά gifts.unlocked (όσα άνοιξε αυτή η απόδειξη, με id) και gifts.pending. 3) Ο ταμίας δίνει το δώρο και πατά Το δώρο δόθηκε: καλέστε POST /v1/members/{member}/gifts/{gift_id}/give. Το αντικείμενο member έχει επίσης gifts.pending. Στέλνονται τα συμβάντα gift.unlocked και gift.given. Καταστήματα χωρίς δώρα δεν παίρνουν ποτέ το πεδίο gifts, και οι διευθύνσεις δώρων απαντούν 404 endpoint_not_found.

Απάντηση · POST /v1/checks/calculate (απόσπασμα)
{
  "object": "check_calculation",
  "amount": 120000,
  "cashback_earned": 6000,
  "gifts": {
    "pending": [],
    "unlocks": [
      { "object": "gift", "id": null, "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "cashier_note": "From the shelf by the till", "status": "pending", "expires_at": "2026-12-16T10:00:00.000Z" }
    ]
  },
  "display": {
    "cashier_text": "Gift: Bottle of wine (hand it to the guest) · Cashback earned: 60.00 MDL · Cashback balance: 210.00 MDL",
    "receipt_lines": ["Gift: Bottle of wine (hand it to the guest)", "Cashback earned: 60.00 MDL", "..."]
  },
  ...
}
Απάντηση · POST /v1/transactions (απόσπασμα)
"gifts": {
  "unlocked": [
    { "object": "gift", "id": "6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2", "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "status": "pending", "unlocked_at": "2026-11-16T10:00:00.000Z", "expires_at": "2026-12-16T10:00:00.000Z", "given_at": null }
  ],
  "pending": [ ... the same gift and any older ones still waiting ... ]
}
Αίτημα · το δώρο δόθηκε
curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/gifts/6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2/give \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: give-6f1c0b7e" \
  -H "Content-Type: application/json" \
  -d '{ "register_id": "401", "cashier": "Ana" }'

Λειτουργίες σφραγίδων

Από προεπιλογή ένα πρόγραμμα σφραγίδων δίνει 1 σφραγίδα ανά απόδειξη. Ο ιδιοκτήτης καταστήματος μπορεί να το αλλάξει στη σελίδα Πρόγραμμα: 1 σφραγίδα ανά απόδειξη που έχει προϊόν από επιλεγμένες κατηγορίες ή 1 σφραγίδα για κάθε μονάδα προϊόντος από επιλεγμένες κατηγορίες (ένα ζυγιζόμενο προϊόν μετρά ως μία μονάδα), καθώς και ελάχιστο ποσό απόδειξης για σφραγίδα. Οι κατηγορίες είναι οι κωδικοί category των line_items ή του καταλόγου σας. Οι λειτουργίες ανά κατηγορία χρειάζονται line_items στα POST /v1/transactions και POST /v1/checks/calculate· απόδειξη χωρίς γραμμές δίνει 1 σφραγίδα και το ελάχιστο ποσό ισχύει για κάθε απόδειξη. Το stamps_earned λέει πόσες σφραγίδες έδωσε η απόδειξη· όταν ξεπερνούν το όριο της κάρτας περισσότερες από μία φορές, ξεκλειδώνουν πολλές ανταμοιβές μαζί και το calculate απαντά επίσης rewards_unlocked. Η ακύρωση αφαιρεί ακριβώς τις σφραγίδες που απομένουν. Στη λειτουργία ανά μονάδα μια απόδειξη επιστρέφεται ανά γραμμές με POST /v1/transactions/{external_id}/refunds: αφαιρούνται οι σφραγίδες των μονάδων που επιστράφηκαν (από αχρησιμοποίητες ανταμοιβές αν χρειαστεί, ποτέ κάτω από το μηδέν) και η απάντηση έχει stamps_reversed. Οι υπόλοιπες αποδείξεις σφραγίδων επιστρέφονται ολόκληρες με ακύρωση. Τα καταστήματα χωρίς λειτουργίες σφραγίδων κρατούν 1 σφραγίδα ανά απόδειξη.

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

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

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

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

curl
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
Ερωτήσεις για μια σύνδεση: api@loyaltyfy.io. Απαντάμε μέσα σε μία εργάσιμη ημέρα.