Greece — FAQ: Παραστατικά & Cloud Terminal API

1) Πώς μπορώ να εκδόσω Τιμολόγιο Πώλησης (1.1) που να είναι ταυτόχρονα και Δελτίο Αποστολής;

Το δελτίο αποστολής συγκεκριμένα δεν υποστηρίζεται αυτή τη στιγμή αλλά έρχεται σύντομα.

Το 1.1 θα το βρείτε εδώ.

2) Στο Πιστωτικό Συσχετιζόμενο (5.1) δεν μπορώ να καταλάβω από το sample file πως δηλώνεις το ΜΑΡΚ στο οποίο συσχετίζεις το πιστωτικό.

Σε ένα παραστατικό Α, βάζουμε ένα μοναδικό cbReceiptReference string π.χ. "ΧΥΖ".

Στο πιστωτικό που συσχετίζεται, βάζουμε το ίδιο reference στην παράμετρο cbPreviousReceiptReference, π.χ.:

{
  "cbPreviousReceiptReference": "ΧΥΖ"
}

3) ISV API — τι ρόλο παίζει στο payments flow;

Το ISV API χρησιμοποιείται καθαρά για το onboarding νέων merchants και δεν έχει σχέση με πληρωμές. Στο payment use-case χρησιμοποιούμε τα ISV credentials για κλήσεις στο Cloud Terminal REST API.

ISV Sale Request:
Δείτε το endpoint εδώ.

Unreferenced Refund (επιστροφές / πιστώσεις):
Δείτε το endpoint εδώ.

Το πρώτο δέχεται ISV credentials — στο object ISVDetails βάζετε το merchantID του εμπόρου κάτω από εσάς στο πεδίο terminalMerchantID. Το unreferenced refund προς το παρόν δεν δέχεται ISV στοιχεία, άρα κάνετε κλήσεις εκεί με τα credentials του εμπόρου.

4) Cloud Terminal API & fiscalisationData

Στο Cloud Terminal API ξεχωρίζουμε:

• τα στοιχεία πληρωμής (ποσό, νόμισμα, κάρτα κ.λπ.), και
  
• τα στοιχεία φοροσήμανσης (τύπος παραστατικού, γραμμές, ΑΦΜ, hash κ.λπ.).

Ό,τι αφορά φορολογία / παραστατικά / myDATA μπαίνει αποκλειστικά μέσα στο object fiscalisationData.

Ενδεικτικά, μέσα στο fiscalisationData θα βρείτε:

• cbChargeItems – ποσά, ΦΠΑ, περιγραφές
• cbPayItems – τρόποι πληρωμής (Card, Cash κ.λπ.)
  
• cbReceiptAmount, cbReceiptMoment, cbReceiptReference – σύνολο, ημερομηνία–ώρα, reference
  
• ftReceiptCase, ftChargeItemCase, ftPayItemCase – decimal Int64
• ftReceiptCaseData.GR – στοιχεία AADE (ΑΦΜ εμπόρου, Σειρά, AA, HashPayload κ.λπ.)

Αν λείπει ή είναι λάθος το fiscalisationData, η πληρωμή μπορεί να περάσει στο acquiring επίπεδο, αλλά η φοροσήμανση θα αποτύχει.

5) Cloud Terminal — ροή κλήσεων (Search Devices, Actions, Sales Requests κ.λπ.)

Την επισκόπηση ροής:
εδώ

Την αναλυτική τεκμηρίωση βήμα-βήμα:
εδώ

6) Μετρητά χωρίς χρήση POS — πώς γίνεται το fiscalization;

Με τον ίδιο τρόπο όπως με κάρτα: στο cbPayItems βάζουμε ftPayItemCase για μετρητά και το request περνάει πάλι από το τερματικό (ως middleware, χωρίς να αλληλεπιδρά ο χρήστης).

{
  "cbPayItems": [
    {
      "amount": 2300,
      "description": "cash",
      "position": 1,
      "currencyCode": "978",
      "moment": "2025-07-17T08:11:06Z",
      "ftPayItemCase": 5139205309155246081
    }
  ],
  "fiscalisationData": {
    "GR": {
      "MerchantVATID": "098000979",
      "Series": "A",
      "AA": 397717,
      "HashAlg": "sha256",
      "HashPayload": "098000979-A-397717-receiptreference1-2025-07-17T08:11:06Z-23.0"
    }
  }
}

7) Tο “cashRegisterId” που το βρίσκω για έναν συγκεκριμένο merchant;

Δεν είναι κάτι που “σας δίνει” η Viva. Είναι δικό σας αναγνωριστικό ταμειακής / ePOS / ERP και μπορείτε να βάλετε ό,τι θέλετε, αρκεί να βγάζει νόημα στο δικό σας σύστημα.

• Συνήθως είναι ένα ID της ταμειακής (π.χ. POS-01, STORE12-REG3).

8) Τι είναι το πεδίο interappCallback;

Aυτό το interface αφορά all-in-ones όπου η εφαρμογή ePOS/ECR/ERP είναι στην ίδια Android (και σύντομα και iOS) συσκευή με το Terminal app της Viva. Το interappCallback λέει στο app της Viva που να επιστρέψει μετά την ολοκλήρωση της πληρωμής ή/και φοροσήμανσης.

9) Υπάρχει κάπου η λίστα τιμών που υποστηρίζεται στο πεδίο unit μέσα στο cbChargeItems;

Δεν επιβάλλουμε αυστηρό validation σε αυτό το πεδίο – είναι ουσιαστικά ελεύθερο κείμενο (“unit of measure”)

10) Σχετικά με το isvDetails

Στο βασικό σενάριο, σας ενδιαφέρει μόνο το terminalMerchantId:

terminalMerchantId → το merchant ID του εμπόρου που είναι κάτω από εσάς (τον ISV).

merchantId, merchantSourceCode → χρησιμοποιούνται μόνο σε multi-merchant σενάρια.

Multi-merchant functionality σημαίνει ότι το ίδιο τερματικό μπορεί να εναλλάσσεται μεταξύ πολλών εμπόρων και να δέχεται πληρωμές εκ μέρους τρίτων (π.χ. πρακτορείο εισιτηρίων που εισπράττει για πολλές εταιρείες).

11) Στο πεδίο sourceCode χρειάζεται να βάλω το sourceCode που έχω ορίσει στον ISV μου; ή δεν είναι υποχρεωτικό να υπάρχει;

Είναι για το account του εμπόρου και δεν είναι υποχρεωτικό, μόνο αν ο έμπορος έχει πολλαπλά wallets (sub-accounts) ή θέλει να tagάρει τις συναλλαγές με διαφορετικό grouping, όπου το source αλλάζχει ανα συναλλαγή. Αλλά στις περισσότερες περιπτώσεις το source ανατίθεται σε διαφορετικές τοποθεσίες, και συνήθως υπάρχει διαφορετικό τερματικό για την καθεμιά.

12) Πώς εκδίδω αποδείξεις σε Order Slip (8.6) — επιμέρους ή συγκεντρωτικά;

Για παραγγελίες τύπου order slip (8.6) υπάρχουν δύο νόμιμες ροές:

1) Άμεση φορολογική απόδειξη ανά παραγγελία (χωρίς 8.6)
Όταν ο πελάτης πληρώνει τη στιγμή της παραγγελίας (μετρητά ή κάρτα), μπορείς να εκδίδεις απευθείας φορολογική απόδειξη, χωρίς να δημιουργήσεις 8.6.

2) Έκδοση 8.6 ανά παραγγελία & τελικού παραστατικού στο τέλος
Για κάθε order εκδίδεται ένα 8.6, και στο τέλος:
- εκδίδεις ένα ή περισσότερα τελικά παραστατικά,
- με line items από τα αρχικά 8.6,
- και reference στα αντίστοιχα 8.6.
Οι πληρωμές μπορούν να γίνουν με μία ή πολλές κάρτες/μετρητά.

Επιτρέπονται ξεχωριστές αποδείξεις για κάθε άτομο;
Ναι. Μπορείς να εκδόσεις πολλαπλά τελικά παραστατικά που αναφέρονται στα ίδια 8.6, αρκεί τα συνολικά ποσά να καλύπτουν πλήρως τα αρχικά order slips.

Παράδειγμα
- 3 μπύρες → 1× 8.6
- 1 σαλάτα → 1× 8.6
- Οι πελάτες θέλουν ξεχωριστούς λογαριασμούς.

Με βάση τον νόμο:
- εκδίδεις 3 τελικά παραστατικά για τις μπύρες (1 ανά άτομο),
- και 1 τελικό παραστατικό για τη σαλάτα, ακόμη κι αν πληρωθεί με 3 διαφορετικές κάρτες.

Για να «σπάσει» η σαλάτα στα 3 άτομα, στέλνεις 3 line items με το ποσό / 3,
καθώς δεν επιτρέπεται να «σπάσεις» ένα line item χωρίς να το αναπαραστήσεις σε ξεχωριστές γραμμές.

13) Στα παραστατικά 11.1 / 11.2, παίρνω πάντα Series και AA από το Viva API και αγνοούνται όσα στέλνω εγώ; Και πρέπει κάθε τύπος παραστατικού (π.χ. 11.1 και 11.2) να έχει διαφορετική σειρά ή αρκεί το AA να είναι μοναδικό μέσα στην ίδια σειρά;

Όχι, δεν είναι υποχρεωτικό να παίρνεις πάντα Series και AA από το Viva API – μπορείς να τα κάνεις override με τις δικές σου τιμές μέσω του ftReceiptCaseData Περισσότερες λεπτομέρειες:
εδώ

Σχετικά με τις σειρές:

Το AA πρέπει να είναι μοναδικό μέσα σε μία συγκεκριμένη Series.

Η ίδια Series μπορεί να επαναχρησιμοποιηθεί για διαφορετικούς τύπους παραστατικών (π.χ. 11.1 και 11.2 δεν είναι υποχρεωτικό να έχουν διαφορετική σειρά).

14) Σε περίπτωση error TRANSMISSION_FAILURE_1 ή TRANSMISSION_FAILURE_2 στο fiscalization θα γίνει trigger κάποιο από τα παραπάνω events στα webhooks αυτά (του 1802 βασικά) ή δεν θα μου έρθει event?

Στα webhooks δε στέλνουμε κάτι γενικότερα αυτή τη στιγμη αλλά έρχεται συντομα.