☰ Μενού · POS και ταμεία
Οδηγοί

POS και ταμεία

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

Η συνηθισμένη ροή στο ταμείο: ο ταμίας σαρώνει την κάρτα Wallet του πελάτη (ή πληκτρολογεί το τηλέφωνο), το ταμείο δείχνει το υπόλοιπο, ο πελάτης αποφασίζει αν θα πληρώσει μέρος της απόδειξης με cashback, η απόδειξη κλείνει και το ταμείο μάς τη στέλνει. Η κάρτα στο κινητό του πελάτη ενημερώνεται μέσα σε λίγα δευτερόλεπτα.

1. Βρείτε τον πελάτη

Το GET /v1/members/{member} δέχεται ό,τι έχει το ταμείο: τον αριθμό κάρτας, το περιεχόμενο του barcode, το τηλέφωνο σε διεθνή μορφή ή το δικό μας id μέλους. Κωδικοποιήστε το τηλέφωνο για URL (το + γίνεται %2B).

curl
# 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
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
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, ... },
    ...
  }
}
Το 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
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
  }'
Απάντηση · 402
{
  "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"
}
Δώστε την έκπτωση από cashback μόνο αφού απαντήσουμε 201 ή 200. Στείλτε την απόδειξη όταν το σύνολο είναι οριστικό, αλλά πριν πάρετε την πληρωμή. Αν δεν υπάρξει απάντηση, ξαναστείλτε με το ίδιο external_id ή κλείστε την απόδειξη χωρίς cashback. Αλλιώς ο πελάτης μπορεί να πάρει την έκπτωση και να κρατήσει το υπόλοιπο.

6. Δώστε την επιβράβευση σφραγίδων

Όταν το stamps.rewards_available είναι πάνω από μηδέν, ο πελάτης δικαιούται δωρεάν προϊόν. Δώστε το από το ταμείο και καταγράψτε το:

curl
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 με τις γραμμές που επιστράφηκαν.

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
curl
curl -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).

JSON
"settings": {
  "offline_max_hours": 72,
  "timeout_seconds": 5,
  "offline_redeem": false
}

Αποδείξεις από τον server του ταμείου

Ορισμένα συστήματα POS δεν μπορούν να καλέσουν API από το ταμείο, μπορούν όμως να στείλουν τις κλεισμένες αποδείξεις από τον server τους. Λειτουργεί κι αυτό: στείλτε το ίδιο POST /v1/transactions από τον server, με τον αριθμό κάρτας που σάρωσε ο ταμίας, μόλις κλείσει η απόδειξη. Εγγραφείτε στο transaction.completed αν το ταμείο θέλει να δείξει το αποτέλεσμα αργότερα.

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