POS και ταμεία

Η συνηθισμένη ροή στο ταμείο: ο ταμίας σαρώνει την κάρτα 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_..."

Δείξτε στον ταμία ό,τι μετράει για το πρόγραμμα, από το αντικείμενο του μέλους:

2. Τι περιέχει το barcode της κάρτας

Η επιχείρηση επιλέγει τη μορφή του barcode στο Προγραμματιστές → Barcode κάρτας, ώστε να ταιριάζει με αυτό που διαβάζει ο σαρωτής του ταμείου:

Η αλλαγή μορφής ενημερώνει και τις κάρτες που βρίσκονται ήδη στα 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",
    "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,
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
    ...
  }
}

Το cashback υπολογίζεται σε ό,τι πλήρωσε πραγματικά ο πελάτης: amount − redeem_amount. Στα προγράμματα σφραγίδων και επισκέψεων η απόδειξη μετράει ως επίσκεψη· τα stamps_earned και reward_unlocked σας λένε τι έγινε, ώστε το ταμείο να μπορεί να πει «ακόμη ένας καφές και ο επόμενος είναι δωρεάν».

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"
}

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 που εξαργυρώθηκε επιστρέφει στον πελάτη. Μερικές επιστροφές: ακυρώστε την απόδειξη και στείλτε νέα με το διορθωμένο ποσό και νέο external_id.

curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."

8. Όταν το ταμείο είναι εκτός σύνδεσης

Βάλτε τις αποδείξεις σε τοπική ουρά με το external_id και το closed_at τους και στείλτε τις όταν επανέλθει η σύνδεση. Τα διπλότυπα αγνοούνται, οπότε μπορείτε με ασφάλεια να ξαναστείλετε ολόκληρη την ουρά. Η αναζήτηση πελάτη χρειάζεται δίκτυο· αν δεν υπάρχει, αφήστε τον ταμία να παραλείψει το πρόγραμμα επιβράβευσης για αυτή την απόδειξη αντί να μπλοκάρει την πώληση.

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

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