☰ Μενού · Συναλλαγές
Συναλλαγές
Μια κλεισμένη απόδειξη που έστειλε ένα ταμείο. Δίνει επιβράβευση, μπορεί να εξαργυρώσει cashback, μπορεί να ακυρωθεί.
Το αντικείμενο transaction
- external_idstring
- Το id της απόδειξής σας. Μοναδικό ανά επιχείρηση.
- statusstring
completedήvoided.- amountinteger
- Ολόκληρη η απόδειξη, στη μικρότερη υποδιαίρεση.
- redeem_amountinteger
- Το ποσό που πληρώθηκε με cashback.
- net_amountinteger
amount − redeem_amount.- cashback_earned, stamps_earnedinteger
- Τι κέρδισε η απόδειξη.
- reward_unlockedboolean
- Αυτή η απόδειξη συμπλήρωσε μια κάρτα σφραγίδων.
- currency, register_id, closed_atstring
- Όπως στάλθηκαν.
- locationobject
- Μόνο όταν η απόδειξη αντιστοιχίστηκε σε κατάστημα με δικούς του κανόνες:
{id, name, store_code, register_id, matched_by}. Τοmatched_byείναιregister_idήstore_id. Δείτε πώς στέλνετε το κατάστημα και το ταμείο. - cashierobject
- Μόνο όταν η απόδειξη στάλθηκε με
cashier:{id, name}. - memberobject
- Το μέλος μετά την απόδειξη, με το νέο υπόλοιπο.
- amount_refundedinteger
- Το σύνολο των μερικών επιστροφών μέχρι τώρα.
- line_itemsarray
- Τα στοιχεία της απόδειξης και τι έκανε το καθένα:
amount(το μερίδιο της γραμμής στην απόδειξη),cashback_earned,earn_percent(null όταν η κατηγορία δεν κερδίζει),redeemable(αν μπορούσε να πληρωθεί με cashback) καιquantity_refunded. Κενό όταν η απόδειξη ήρθε χωρίς στοιχεία. - line_items[].promoboolean
- Μόνο για καταστήματα με κανόνες προσφορών: αν η γραμμή στάλθηκε ως προϊόν σε προσφορά.
- displayobject
- Τα
cashier_textκαιreceipt_linesστη γλώσσα του πελάτη, έτοιμα για εκτύπωση.
/v1/transactionsΚαταχωρίζει μία κλεισμένη απόδειξη. Η επανάληψη ενός external_id επιστρέφει το αποθηκευμένο αποτέλεσμα με 200. Τα card_number και gross_amount γίνονται δεκτά ως ψευδώνυμα των member και amount.
- external_idstring, υποχρεωτικό
- Το id της απόδειξής σας, έως 128 χαρακτήρες.
- memberstring, υποχρεωτικό
- Αριθμός κάρτας, τιμή σάρωσης, serial, id μέλους ή τηλέφωνο.
- amountinteger, υποχρεωτικό
- Ολόκληρη η απόδειξη πριν από το cashback, στη μικρότερη υποδιαίρεση, μεγαλύτερη από μηδέν.
- redeem_amountinteger
- Το cashback που χρησιμοποιεί ο πελάτης σε αυτή την απόδειξη. Προεπιλογή 0. Περιορίζεται από το υπόλοιπο και το
redeem_max_percentτου προγράμματος. - currencystring
- ISO 4217. Προεπιλογή: το νόμισμα του προγράμματος.
- closed_atdatetime
- Πότε έκλεισε η απόδειξη, σε ISO 8601 με offset. Προεπιλογή: τώρα.
- register_idstring
- Το id του ταμείου ή του καταστήματός σας. Εμφανίζεται στις αναφορές. Αν ο ιδιοκτήτης έχει συνδέσει αυτόν τον κωδικό με κατάστημα, η απόδειξη ακολουθεί τους κανόνες cashback του καταστήματος.
- store_idstring
- Ο κωδικός καταστήματος από το λογιστικό σας σύστημα, έως 64 χαρακτήρες. Χρησιμοποιείται όταν λείπει το
register_idή δεν είναι συνδεδεμένο με κανένα κατάστημα. Όταν δείχνουν σε διαφορετικά καταστήματα, υπερισχύει τοregister_id. Δείτε πώς στέλνετε το κατάστημα και το ταμείο. - cashierstring or object
- Ποιος χτύπησε την απόδειξη, όπως τον ξέρει το ταμείο σας: ένα κείμενο (όνομα ή κωδικός) ή
{id, name}. Αποθηκεύεται με την απόδειξη και επιστρέφεται στοcashier. Δεν αλλάζει ποτέ το cashback και δεν μπαίνει στον έλεγχο idempotency. Τα σήματα ταμιών του ιδιοκτήτη το χρησιμοποιούν για να δείξουν ποιος χτύπησε μια ύποπτη απόδειξη. - hold_iduuid
- Επιβεβαιώνει αυτή τη δέσμευση αντί να στείλετε
redeem_amount. - discount_typestring
- Ο κωδικός έκπτωσης αυτής της απόδειξης (
employee,discount_card,promo), έως 64 χαρακτήρες. Με ενεργούς τύπους έκπτωσης ισχύουν οι κανόνες του ιδιοκτήτη. Μια γραμμή μπορεί να έχει και δικό τηςdiscount_type. - line_items[].promoboolean
trueόταν το προϊόν είναι σε προσφορά. Τότε οι κανόνες προσφορών του ιδιοκτήτη αποφασίζουν αν η γραμμή δίνει cashback και αν πληρώνεται με cashback. Αγνοείται αν το κατάστημα δεν ενεργοποίησε τον κανόνα.- line_itemsarray
- Έως 500 στοιχεία
{sku, name, quantity, unit_price, category}. Αποθηκεύονται μαζί με την απόδειξη για τις αναφορές προϊόντων και χρησιμοποιούνται από τους κανόνες κατηγοριών: κατηγορία χωρίς cashback, που δεν πληρώνεται με cashback (προϊόντα σε προσφορά) ή με δικό της ποσοστό. Χωρίςcategoryβρίσκουμε την κατηγορία από τοskuστον κατάλογο. Χωρίς στοιχεία, όλη η απόδειξη κερδίζει στο επίπεδο του πελάτη.
Πώς στέλνετε το κατάστημα και το ταμείο
Στείλτε δύο προαιρετικές συμβολοσειρές με κάθε απόδειξη (POST /v1/transactions), υπολογισμό (POST /v1/checks/calculate) και δέσμευση (POST /v1/holds): το register_id είναι ο κωδικός του ταμείου, το store_id είναι ο κωδικός του καταστήματος στο λογιστικό σας σύστημα, έως 64 χαρακτήρες. Ο ιδιοκτήτης καταχωρεί και τους δύο κωδικούς στην ενότητα Καταστήματα. Το κατάστημα αναζητείται πρώτα με το register_id· αν ο κωδικός ταμείου λείπει ή δεν είναι συνδεδεμένος με κανένα κατάστημα, με το store_id. Αν σταλούν και τα δύο και δείχνουν σε διαφορετικά καταστήματα, υπερισχύει το register_id. Αν δεν βρεθεί τίποτα, η απόδειξη ακολουθεί τους γενικούς κανόνες και οι άγνωστοι κωδικοί εμφανίζονται στον ιδιοκτήτη στη λίστα "μη συνδεδεμένοι". Οι κωδικοί λειτουργούν όταν το κατάστημα έχει ενεργούς κανόνες ανά σημείο· αλλιώς τα πεδία αγνοούνται. Στέλνετε και τα δύο πεδία με κάθε απόδειξη, ακόμη και με ένα μόνο κατάστημα.
{
"external_id": "000131",
"member": "2000111703779",
"amount": 12550,
"store_id": "122927",
"register_id": "122930",
"line_items": [
{ "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
{ "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
]
}Ο υπολογισμός και η συναλλαγή έχουν τότε ένα αντικείμενο location με το κατάστημα όπου υπολογίστηκε η απόδειξη: id, name, store_code, register_id και matched_by (register_id ή store_id). Χωρίς location στην απάντηση, η απόδειξη ακολούθησε τους γενικούς κανόνες.
{
"object": "transaction",
"external_id": "000131",
"register_id": "122930",
...
"location": {
"object": "location",
"id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
"name": "Store 1",
"store_code": "122927",
"register_id": "122930",
"matched_by": "register_id"
}
}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, ... },
...
}
}/v1/transactions/{external_id}Επιστρέφει μία συναλλαγή με βάση το id της απόδειξής σας.
/v1/transactions/{external_id}/voidΑναιρεί μια απόδειξη: το cashback και οι σφραγίδες που κερδήθηκαν αφαιρούνται, το cashback που εξαργυρώθηκε επιστρέφεται. Η διπλή ακύρωση δεν προκαλεί πρόβλημα.
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."{
"object": "transaction",
"id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
"external_id": "CHK-2026-000123",
"status": "voided",
"amount": 25000,
"cashback_earned": 1250,
"voided_at": "2026-10-06T18:17:21.003+00:00",
"member": {
"object": "member",
"id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
"card_number": "2000111703779",
"cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
...
},
...
}/v1/transactions/{external_id}/refundsΕπιστρέφει μέρος μιας απόδειξης με cashback, κατά amount ή κατά line_items. Κατά ποσό, το cashback υπολογίζεται αναλογικά με την απόδειξη. Κατά γραμμές, το cashback ακολουθεί όσα κέρδισε πραγματικά κάθε γραμμή: ένα προϊόν σε προσφορά που δεν κέρδισε τίποτα δεν αφαιρεί τίποτα, και το cashback που ξόδεψε ο πελάτης επιστρέφει μόνο για γραμμές που μπορούσαν να πληρωθούν με αυτό. Στείλτε το δικό σας external_id της επιστροφής· η επανάληψή του είναι ασφαλής. Επιτρέπονται πολλές επιστροφές ανά απόδειξη· η τελευταία κλείνει ακριβώς τα υπόλοιπα. Οι αποδείξεις προγραμμάτων με σφραγίδες και επισκέψεις επιστρέφονται ολόκληρες με ακύρωση.
- external_idstring, υποχρεωτικό
- Το δικό σας id αυτής της επιστροφής, έως 128 χαρακτήρες.
- amountinteger
- Το ποσό που επιστράφηκε, σε ελάχιστες μονάδες. Μην το στείλετε όταν τα
line_itemsλένε τι επιστράφηκε. - line_itemsarray
- Οι γραμμές που επιστράφηκαν:
{sku, quantity}ή{name, quantity}, ακριβώς όπως στην απόδειξη. Οι μονάδες που έχουν ήδη επιστραφεί μετρούν· αν ζητηθούν περισσότερες, απαντάrefund_exceeds_lineμεrefundable. Απόδειξη που στάλθηκε χωρίς γραμμές απαντάno_line_items: επιστρέψτε την κατά ποσό. - line_items[].promoboolean
- Γίνεται δεκτό και αγνοείται: η επιστροφή ακολουθεί ό,τι έδωσε και μπορούσε να πληρώσει η αρχική γραμμή.
- register_idstring
- Το id του ταμείου σας, για αρίθμηση ανά ταμείο.
- store_idstring
- Ο κωδικός του καταστήματός σας. Γίνεται δεκτός για συμμετρία με την απόδειξη· η επιστροφή ακολουθεί το κατάστημα της αρχικής απόδειξης.
# 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 back{
"object": "refund",
"id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
"external_id": "RET-2026-000017",
"transaction": "CHK-2026-000124",
"amount": 5000,
"cashback_reversed": 200,
"redeem_restored": 1000,
"line_items": [],
"livemode": false,
"created_at": "2026-10-06T18:40:02.000+00:00",
"transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}
// by lines
{
"object": "refund",
"external_id": "RET-2026-000018",
"transaction": "CHK-2026-000130",
"amount": 4500,
"cashback_reversed": 450,
"redeem_restored": 0,
"line_items": [
{ "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
],
...
}/v1/transactions/{external_id}/returnsΕπιστρέφει μία ή περισσότερες γραμμές μιας απόδειξης: ο πελάτης φέρνει πίσω ένα από τρία προϊόντα. Το cashback που κερδήθηκε σε αυτές τις γραμμές αφαιρείται και το cashback με το οποίο τις πλήρωσε επιστρέφει, με βάση όσα κέρδισε πραγματικά κάθε γραμμή και με τι μπορούσε να πληρωθεί, ποτέ αναλογικά με την απόδειξη. Η απάντηση είναι το ίδιο αντικείμενο με μια επιστροφή, με object: "return". Στείλτε το δικό σας external_id της επιστροφής· η επανάληψή του είναι ασφαλής. Αποδείξεις που στάλθηκαν χωρίς line_items δεν επιστρέφονται ανά γραμμή: επιστρέψτε τις κατά amount.
- external_idstring, υποχρεωτικό
- Το δικό σας id αυτής της επιστροφής, έως 128 χαρακτήρες.
- line_itemsarray, υποχρεωτικό
- Οι γραμμές που επιστράφηκαν:
{sku, quantity}ή{name, quantity}, ακριβώς όπως στην απόδειξη. Οι μονάδες που έχουν ήδη επιστραφεί μετρούν· αν ζητηθούν περισσότερες, απαντάrefund_exceeds_lineμεrefundable. - line_items[].promoboolean
- Γίνεται δεκτό και αγνοείται: η επιστροφή ακολουθεί ό,τι έδωσε και μπορούσε να πληρώσει η αρχική γραμμή.
- register_idstring
- Το id του ταμείου σας, για αρίθμηση ανά ταμείο.
- store_idstring
- Ο κωδικός του καταστήματός σας. Γίνεται δεκτός για συμμετρία με την απόδειξη· η επιστροφή ακολουθεί το κατάστημα της αρχικής απόδειξης.
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'
# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back{
"object": "return",
"id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
"external_id": "RET-2026-000019",
"transaction": "CHK-2026-000130",
"amount": 4500,
"cashback_reversed": 450,
"redeem_restored": 0,
"line_items": [
{ "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
],
"livemode": false,
"created_at": "2026-11-06T09:12:40.000+00:00",
"transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}/v1/transactionsΕπιστρέφει τις συναλλαγές, με τις νεότερες πρώτες. Φιλτράρισμα με ?member=. Με σελιδοποίηση.