☰ Μενού · POS και ταμεία
POS και ταμεία
Όλα όσα χρειάζεται ένα ταμείο: εύρεση πελάτη, καταχώριση απόδειξης, εξαργύρωση cashback, επιστροφές και έκδοση καρτών με τους αριθμούς του ίδιου του ταμείου.
Η συνηθισμένη ροή στο ταμείο: ο ταμίας σαρώνει την κάρτα Wallet του πελάτη (ή πληκτρολογεί το τηλέφωνο), το ταμείο δείχνει το υπόλοιπο, ο πελάτης αποφασίζει αν θα πληρώσει μέρος της απόδειξης με cashback, η απόδειξη κλείνει και το ταμείο μάς τη στέλνει. Η κάρτα στο κινητό του πελάτη ενημερώνεται μέσα σε λίγα δευτερόλεπτα.
1. Βρείτε τον πελάτη
Το GET /v1/members/{member} δέχεται ό,τι έχει το ταμείο: τον αριθμό κάρτας, το περιεχόμενο του barcode, το τηλέφωνο σε διεθνή μορφή ή το δικό μας id μέλους. Κωδικοποιήστε το τηλέφωνο για URL (το + γίνεται %2B).
# by the number on the card (or the barcode the scanner read)
curl https://loyaltyfy.io/api/v1/members/2000111703779 \
-H "Authorization: Bearer sk_test_..."
# by phone, with fresh add-to-wallet links
curl "https://loyaltyfy.io/api/v1/members/%2B37366791102?expand=wallet" \
-H "Authorization: Bearer sk_test_..."Δείξτε στον ταμία ό,τι μετράει για το πρόγραμμα, από το αντικείμενο του μέλους:
| program.mechanic | Τι δείχνετε |
|---|---|
| cashback | Το cashback.available και το μέγιστο ποσό εξαργύρωσης: το μικρότερο ανάμεσα στο υπόλοιπο και στο redeem_max_percent της απόδειξης. |
| stamps | Το stamps.current από stamps.required, και το stamps.rewards_available αν ο πελάτης έχει δωρεάν προϊόν που τον περιμένει. |
| visit_discount, vip | Τα discount.percent και discount.tier: εφαρμόστε εσείς αυτή την έκπτωση στην απόδειξη. |
2. Τι περιέχει το barcode της κάρτας
Η επιχείρηση επιλέγει τη μορφή του barcode στο Προγραμματιστές → Barcode κάρτας, ώστε να ταιριάζει με αυτό που διαβάζει ο σαρωτής του ταμείου:
| Μορφή | Τι περιέχει το barcode | Πότε τη χρησιμοποιείτε |
|---|---|---|
| QR με τον αριθμό κάρτας | Το card_number, για παράδειγμα 2000111703779 | Ο σαρωτής διαβάζει QR και το ταμείο αναζητά με αριθμό κάρτας. Προτείνεται. |
| Barcode (Code 128) με τον αριθμό κάρτας | Τον ίδιο αριθμό ως γραμμικό barcode, τυπωμένο κάτω από τις γραμμές | Παλαιότεροι σαρωτές laser που δεν διαβάζουν QR. |
| QR για το ταμείο Loyaltyfy | Το εσωτερικό μας serial (ένα UUID) | Η προεπιλογή. Το διαβάζει μόνο η εφαρμογή ταμείου του Loyaltyfy· ένα POS μπορεί πάντα να βρει τον πελάτη με το τηλέφωνο. |
Η αλλαγή μορφής ενημερώνει και τις κάρτες που βρίσκονται ήδη στα Wallet των πελατών· κανείς δεν χρειάζεται να εγκαταστήσει κάτι ξανά. Όποια κι αν είναι η μορφή, στείλτε την τιμή της σάρωσης ως έχει στο GET /v1/members/{member} ή στο POST /v1/scans, το οποίο αφαιρεί επίσης προθέματα σαρωτή και αλλαγές γραμμής.
3. Εκδώστε κάρτες με τους αριθμούς του ταμείου
Αν το ταμείο έχει ήδη σύστημα καρτών, κρατήστε τους αριθμούς του. Εγγράψτε τον πελάτη με card_number ίσο με τον αριθμό του ταμείου· η κάρτα Wallet δείχνει αυτόν τον αριθμό και το barcode της τον κωδικοποιεί, οπότε ο σαρωτής βρίσκει τον πελάτη και στη βάση του ίδιου του ταμείου. Οι αριθμοί είναι μοναδικοί ανά επιχείρηση: ένα διπλότυπο λαμβάνει 409 card_number_taken. Για να δώσετε αργότερα αριθμό ταμείου σε υπάρχον μέλος, χρησιμοποιήστε PATCH /v1/members/{member} με card_number.
curl https://loyaltyfy.io/api/v1/members \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d1b2c4e-enrol-000123" \
-d '{
"phone": "+37366791102",
"first_name": "Ion",
"last_name": "Popescu",
"card_number": "2000111703779",
"language": "ro",
"consent": true
}'Η απάντηση περιέχει τα wallet.apple_url και wallet.google_url. Τυπώστε τα ως QR στην απόδειξη, στείλτε τα με SMS ή δείξτε τα στην οθόνη πελάτη: ο πελάτης ανοίγει τον σύνδεσμο και η κάρτα προστίθεται στο κινητό.
4. Περάστε την απόδειξη
Στείλτε κάθε κλεισμένη απόδειξη μία φορά, μετά την πληρωμή. Το amount είναι ολόκληρη η απόδειξη πριν από οποιοδήποτε cashback· το redeem_amount είναι το μέρος που πλήρωσε ο πελάτης με cashback. Εφαρμόζουμε τους κανόνες του προγράμματος (ελάχιστη απόδειξη, όριο εξαργύρωσης, επίπεδα) όπως ακριβώς και η οθόνη ταμία της επιχείρησης.
curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": "CHK-2026-000123",
"member": "2000111703779",
"amount": 25000,
"currency": "MDL",
"register_id": "POS-1",
"store_id": "S-1",
"closed_at": "2026-10-06T18:17:00+03:00",
"line_items": [
{ "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
{ "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
]
}'{
"object": "transaction",
"id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
"external_id": "CHK-2026-000123",
"status": "completed",
"amount": 25000,
"redeem_amount": 0,
"cashback_earned": 1250,
"stamps_earned": 0,
"reward_unlocked": false,
"net_amount": 25000,
"currency": "MDL",
"register_id": "POS-1",
"closed_at": "2026-10-06T15:17:00+00:00",
"livemode": false,
"created_at": "2026-10-06T18:17:17.921+00:00",
"voided_at": null,
"amount_refunded": 0,
"line_items": [
{ "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
{ "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
],
"member": {
"object": "member",
"id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
"card_number": "2000111703779",
"cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
...
}
}external_id πρέπει να είναι μοναδικό σε όλα τα ταμεία της επιχείρησης. Αν η αρίθμηση αποδείξεων ξεκινά από την αρχή σε κάθε ταμείο ή βάρδια, συνδυάστε τα, για παράδειγμα POS-3-000123 (ταμείο 3, απόδειξη 123).Το cashback υπολογίζεται σε ό,τι πλήρωσε πραγματικά ο πελάτης: amount − redeem_amount. Στα προγράμματα σφραγίδων και επισκέψεων η απόδειξη μετράει ως επίσκεψη· τα stamps_earned και reward_unlocked σας λένε τι έγινε, ώστε το ταμείο να μπορεί να πει «ακόμη ένας καφές και ο επόμενος είναι δωρεάν».
Αν ο ιδιοκτήτης ενεργοποίησε τον κανόνα «σε μία επίσκεψη ο πελάτης ή συγκεντρώνει ή εξαργυρώνει», μια απόδειξη με εξαργύρωση (redeem_amount πάνω από 0 ή ένα hold_id) δεν δίνει cashback: το cashback_earned είναι 0, κάθε γραμμή έχει cashback_earned 0 και earn_percent null, και η απάντηση των POST /v1/checks/calculate και POST /v1/transactions περιέχει earn_blocked: "redeemed". Η επίσκεψη μετράει κανονικά (επισκέψεις, δαπάνη, επίπεδα). Η επόμενη απόδειξη χωρίς εξαργύρωση δίνει cashback ως συνήθως. Χωρίς τον κανόνα δεν υπάρχει πεδίο earn_blocked.
5. Πληρωμή με cashback
Ζητήστε πρώτα το υπόλοιπο, αφήστε τον πελάτη να επιλέξει και μετά στείλτε την απόδειξη με redeem_amount. Αν το υπόλοιπο άλλαξε στο μεταξύ (ο πελάτης πλήρωσε κάπου αλλού πριν από ένα δευτερόλεπτο), λαμβάνετε 402 insufficient_balance με το τρέχον ποσό available· δείξτε το και αφήστε τον ταμία να ξαναδοκιμάσει.
curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": "CHK-2026-000124",
"member": "2000111703779",
"amount": 12000,
"redeem_amount": 1250
}'{
"error": {
"type": "invalid_request_error",
"code": "insufficient_balance",
"message": "redeem_amount is more than the available balance.",
"param": "redeem_amount",
"available": 1250
},
"request_id": "req_6f4c30b8ca7d4423a9d4"
}201 ή 200. Στείλτε την απόδειξη όταν το σύνολο είναι οριστικό, αλλά πριν πάρετε την πληρωμή. Αν δεν υπάρξει απάντηση, ξαναστείλτε με το ίδιο external_id ή κλείστε την απόδειξη χωρίς cashback. Αλλιώς ο πελάτης μπορεί να πάρει την έκπτωση και να κρατήσει το υπόλοιπο.6. Δώστε την επιβράβευση σφραγίδων
Όταν το stamps.rewards_available είναι πάνω από μηδέν, ο πελάτης δικαιούται δωρεάν προϊόν. Δώστε το από το ταμείο και καταγράψτε το:
curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/rewards/redeem \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: reward-4285324286429-0001"7. Επιστροφές και λάθη
Ακυρώστε μια απόδειξη ολόκληρη με το external_id της: το cashback ή οι σφραγίδες που κερδίστηκαν αφαιρούνται, το cashback που εξαργυρώθηκε επιστρέφει στον πελάτη. Για μερική επιστροφή στείλτε POST /v1/transactions/{external_id}/refunds είτε με το ποσό amount είτε με τις γραμμές line_items που επιστράφηκαν (κωδικός και ποσότητα): κατά γραμμές, το cashback ακολουθεί όσα κέρδισε πραγματικά η καθεμία, άρα η επιστροφή ενός από τρία προϊόντα αφαιρεί ακριβώς το cashback του. Μια ακυρωμένη ή πλήρως επιστραμμένη απόδειξη δεν μετρά πια ως επίσκεψη και δαπάνη, άρα οι επιστροφές δεν ανεβάζουν ποτέ το επίπεδο του πελάτη. Ένα ταμείο με κουμπί «επιστροφή προϊόντος» καλεί POST /v1/transactions/{external_id}/returns με τις γραμμές που επιστράφηκαν.
# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000017", "amount": 5000 }'
# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'
# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken backcurl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."8. Όταν το ταμείο είναι εκτός σύνδεσης
Βάλτε τις αποδείξεις σε τοπική ουρά με το external_id και το closed_at τους και στείλτε τις όταν επανέλθει η σύνδεση. Τα διπλότυπα αγνοούνται, οπότε μπορείτε με ασφάλεια να ξαναστείλετε ολόκληρη την ουρά. Η αναζήτηση πελάτη χρειάζεται δίκτυο· αν δεν υπάρχει, αφήστε τον ταμία να παραλείψει το πρόγραμμα επιβράβευσης για αυτή την απόδειξη αντί να μπλοκάρει την πώληση.
Περιμένετε την απάντησή μας 3 έως 5 δευτερόλεπτα. Αν δεν έρθει, κλείστε την απόδειξη χωρίς επιβράβευση και βάλτε τη στην ουρά· η συλλογή θα γίνει αργότερα, όταν σταλεί η ουρά. Κάντε το ίδιο αν η βλάβη είναι σε εμάς: μια αργή ή αποτυχημένη απάντηση από εμάς δεν πρέπει ποτέ να καθυστερεί την πώληση. Η εξαργύρωση cashback χωρίς την απάντησή μας δεν επιτρέπεται: χωρίς σύνδεση δεν βλέπουμε το υπόλοιπο και δύο καταστήματα θα μπορούσαν να ξοδέψουν τα ίδια χρήματα ταυτόχρονα.
Αν το κατάστημα έχει ορίσει κανόνες εκτός σύνδεσης στο Προγραμματιστές → Κανόνες ταμείων, το GET /v1/account τους επιστρέφει στο settings: timeout_seconds (πόσο να περιμένετε, 2 έως 30, προεπιλογή 5), offline_redeem (πάντα false) και offline_max_hours (πόσο αργά γίνεται ακόμη δεκτή μια απόδειξη από την ουρά· προτείνουμε 72).
"settings": {
"offline_max_hours": 72,
"timeout_seconds": 5,
"offline_redeem": false
}Αποδείξεις από τον server του ταμείου
Ορισμένα συστήματα POS δεν μπορούν να καλέσουν API από το ταμείο, μπορούν όμως να στείλουν τις κλεισμένες αποδείξεις από τον server τους. Λειτουργεί κι αυτό: στείλτε το ίδιο POST /v1/transactions από τον server, με τον αριθμό κάρτας που σάρωσε ο ταμίας, μόλις κλείσει η απόδειξη. Εγγραφείτε στο transaction.completed αν το ταμείο θέλει να δείξει το αποτέλεσμα αργότερα.