☰ Μενού · Συναλλαγές
Αναφορά API

Συναλλαγές

Μια κλεισμένη απόδειξη που έστειλε ένα ταμείο. Δίνει επιβράβευση, μπορεί να εξαργυρώσει 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 στη γλώσσα του πελάτη, έτοιμα για εκτύπωση.
POST/v1/transactions
Δικαίωμα: transactions:write

Καταχωρίζει μία κλεισμένη απόδειξη. Η επανάληψη ενός 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. Αν δεν βρεθεί τίποτα, η απόδειξη ακολουθεί τους γενικούς κανόνες και οι άγνωστοι κωδικοί εμφανίζονται στον ιδιοκτήτη στη λίστα "μη συνδεδεμένοι". Οι κωδικοί λειτουργούν όταν το κατάστημα έχει ενεργούς κανόνες ανά σημείο· αλλιώς τα πεδία αγνοούνται. Στέλνετε και τα δύο πεδία με κάθε απόδειξη, ακόμη και με ένα μόνο κατάστημα.

Αίτημα · POST /v1/transactions
{
  "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 στην απάντηση, η απόδειξη ακολούθησε τους γενικούς κανόνες.

Απάντηση · 201 (απόσπασμα)
{
  "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
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" }
    ]
  }'
Απάντηση · 201
{
  "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, ... },
    ...
  }
}
GET/v1/transactions/{external_id}
Δικαίωμα: transactions:write

Επιστρέφει μία συναλλαγή με βάση το id της απόδειξής σας.

POST/v1/transactions/{external_id}/void
Δικαίωμα: transactions:write

Αναιρεί μια απόδειξη: το cashback και οι σφραγίδες που κερδήθηκαν αφαιρούνται, το cashback που εξαργυρώθηκε επιστρέφεται. Η διπλή ακύρωση δεν προκαλεί πρόβλημα.

curl
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."
Απάντηση · 200
{
  "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, ... },
    ...
  },
  ...
}
POST/v1/transactions/{external_id}/refunds
Δικαίωμα: transactions:write

Επιστρέφει μέρος μιας απόδειξης με 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
Ο κωδικός του καταστήματός σας. Γίνεται δεκτός για συμμετρία με την απόδειξη· η επιστροφή ακολουθεί το κατάστημα της αρχικής απόδειξης.
curl
# 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
Απάντηση · 201
{
  "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 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
Δικαίωμα: transactions:write

Επιστρέφει μία ή περισσότερες γραμμές μιας απόδειξης: ο πελάτης φέρνει πίσω ένα από τρία προϊόντα. Το 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
Ο κωδικός του καταστήματός σας. Γίνεται δεκτός για συμμετρία με την απόδειξη· η επιστροφή ακολουθεί το κατάστημα της αρχικής απόδειξης.
curl
# 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
"Απάντηση · 201"
{
  "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": { ... }, ... }
}
GET/v1/transactions
Δικαίωμα: transactions:write

Επιστρέφει τις συναλλαγές, με τις νεότερες πρώτες. Φιλτράρισμα με ?member=. Με σελιδοποίηση.

Ερωτήσεις για μια σύνδεση: api@loyaltyfy.io. Απαντάμε μέσα σε μία εργάσιμη ημέρα.