Έκδοση παραστατικών¶
Τύποι, αρίθμηση, χαρακτηρισμοί, PDF, email στον λήπτη.
Ο χαρακτηρισμός εσόδων για το Ε3 (incomeClassification) στέλνεται μαζί με το παραστατικό ή είναι ξεχωριστή ενέργεια μετά την έκδοση;
Στέλνεται μαζί με το ίδιο το παραστατικό, στην ίδια κλήση SendInvoices, και είναι ευθύνη της εφαρμογής σας. Κάθε γραμμή εσόδου έχει incomeClassification (classificationType, classificationCategory και amount ίσο με το netValue), και το invoiceSummary.incomeClassification έχει τα αθροίσματα ανά τύπο και κατηγορία. Για έξοδα (π.χ. αυτοτιμολόγηση) χρησιμοποιείται το expensesClassification. Οι τιμές (π.χ. E3_561_001 με category1_1) προέρχονται από τους πίνακες χαρακτηρισμών της ΑΑΔΕ, ανάλογα με τη δραστηριότητα.
Δείτε: Τιμολόγια & αποδείξεις
Μπορώ να στείλω αναδρομικά χαρακτηρισμούς εσόδων για παραστατικά που έχουν ήδη εκδοθεί μέσω Παρόχου χωρίς χαρακτηρισμό;
Όχι μέσω του Provider API: μέσω Παρόχου ο χαρακτηρισμός διαβιβάζεται μόνο μαζί με το παραστατικό, τη στιγμή της έκδοσης. Για τα παλιά παραστατικά οι χαρακτηρισμοί μπορούν να γίνουν από τον λογιστή, στο λογιστικό του πρόγραμμα ή απευθείας στο myDATA. Εναλλακτικά χρειάζεται ξεχωριστή διασύνδεση με το κανάλι ERP της ΑΑΔΕ (μέθοδος SendIncomeClassification) με τα διαπιστευτήρια myDATA του πελάτη, εκτός Novus. Για τα νέα παραστατικά διορθώστε το payload ώστε να περιέχει τους χαρακτηρισμούς.
Τι επιστρέφει το API μετά την έκδοση ενός παραστατικού, και μπορώ να τυπώνω δικό μου παραστατικό με αυτά τα στοιχεία;
Η απάντηση είναι σύγχρονη, στην ίδια κλήση SendInvoices. Με statusCode = Success παίρνετε invoiceMark (MARK), invoiceUid, authenticationCode, invoiceUrl/qrUrl (link στο PDF, που τυπώνεται ως QR) και aadeQrUrl, ενώ σε σφάλμα παίρνετε το statusCode και τα errors. Μπορείτε να δίνετε στον πελάτη το PDF του Παρόχου ή να τυπώνετε δικό σας παραστατικό. Αν τυπώνετε δικό σας, πρέπει να έχει τουλάχιστον την επωνυμία και τον ιστότοπο του Παρόχου, το QR code, τα MARK, UID και Authentication Code, και την ημερομηνία και ώρα έκδοσης.
Δείτε: SendInvoices
Ποιος ορίζει τη σειρά και τον αύξοντα αριθμό (series, aa), γίνονται δεκτά ελληνικά γράμματα και μπορώ να συνεχίσω την αρίθμηση που είχα πριν τον Πάροχο;
Τα series και aa τα ορίζει αποκλειστικά η εφαρμογή σας και ο Πάροχος τα διαβιβάζει χωρίς αλλαγή· εσείς φροντίζετε για αρίθμηση χωρίς κενά και διπλότυπα. Ελληνικοί χαρακτήρες στη σειρά υποστηρίζονται (string έως 50 χαρακτήρες, "0" αν δεν υπάρχει σειρά). Ο Πάροχος δεν επιβάλλει περιορισμό στη συνέχεια της αρίθμησης, οπότε μπορείτε να συνεχίσετε από τον αριθμό που είχατε φτάσει. Προσοχή: ίδιος εκδότης, ημερομηνία, εγκατάσταση, τύπος, σειρά και ΑΑ δίνουν ίδιο UID και η δεύτερη αποστολή απορρίπτεται ως διπλότυπο.
Δείτε: SendInvoices
Είναι υποχρεωτικά τα πεδία lineUnitPrice, totalNetPriceBeforeDiscount και vatCategoryPercent στις γραμμές του παραστατικού;
Ναι. Δεν πηγαίνουν στην ΑΑΔΕ, αλλά είναι στοιχεία του PDF (τιμή μονάδας, αξία πριν την έκπτωση, συντελεστής ΦΠΑ) και τα στέλνετε σε κάθε γραμμή. Όταν οι τιμές δεν περιλαμβάνουν ΦΠΑ, στη στήλη της αξίας δείξτε την καθαρή αξία.
Δείτε: SendInvoices
Μπορώ να τυπώνω ή να στέλνω το παραστατικό με δικό μου template αντί για το PDF του Παρόχου;
Ναι. Το API επιστρέφει πάντα έτοιμο PDF του Παρόχου (invoiceUrl) μαζί με τα στοιχεία του παραστατικού, αλλά μπορείτε να φτιάχνετε δικό σας PDF ή εκτύπωση. Τότε το έντυπο πρέπει να έχει την επωνυμία και τον ιστότοπο του Παρόχου, το QR code (από το invoiceUrl / qrUrl), MARK, UID, Authentication Code, ημερομηνία και ώρα έκδοσης, τα στοιχεία πληρωμής POS όπου υπάρχουν και την ένδειξη απώλειας διασύνδεσης σε offline έκδοση. Στην πιστοποίηση υποβάλλετε δείγμα της εκτύπωσής σας (σενάριο Β3), εκτός αν δίνετε στον πελάτη το PDF του Παρόχου.
Ποια ημερομηνία και ώρα έκδοσης τυπώνω σε δικό μου έντυπο, όταν το PDF παράγεται αργότερα από την έκδοση;
Τυπώνετε την τοπική ημερομηνία και ώρα που δημιουργήθηκε (εκδόθηκε) το παραστατικό στο σύστημά σας, όχι τη στιγμή που αργότερα παράγεται ή ξανατυπώνεται το PDF. Η ημερομηνία πρέπει να συμφωνεί με το issueDate που στάλθηκε, που μέσω Παρόχου είναι η σημερινή (εκτός από την περίπτωση transmissionFailure = 1). Ημερομηνία και ώρα πρέπει να είναι ευανάγνωστες.
Γιατί απορρίπτεται ο Τίτλος Κτήσης (τύπος 3.1) που στέλνω;
Ο τύπος 3.1 είναι παραστατικό αγοράς, άρα για τον εκδότη αφορά έξοδο. Γι' αυτό, και στις γραμμές (invoiceDetails) και στη σύνοψη (invoiceSummary), στέλνετε expensesClassification με κατηγορίες category2_… και όχι incomeClassification. Δείτε το έτοιμο παράδειγμα 3.1 στον οδηγό.
Δείτε: Τιμολόγια & αποδείξεις
Μπορώ να εκδίδω αποδείξεις λιανικής μέσω του API χωρίς ταμειακή μηχανή ή φορολογικό μηχανισμό;
Ναι. Μέσω του Παρόχου εκδίδετε παραστατικά λιανικής (11.x), και στην εστίαση τα δελτία παραγγελίας 8.6 με την απόδειξη που τα κλείνει, χωρίς ταμειακή μηχανή ή ΕΑΦΔΣΣ· η λύση λειτουργεί εξ ολοκλήρου στο cloud. Ο Πάροχος τα διαβιβάζει στο myDATA και παράγει PDF με QR και όλα τα υποχρεωτικά στοιχεία. Αν ο πελάτης σας κάνει συναλλαγές B2C, στο αίτημα ενεργοποίησης δηλώνεται και ο πάροχος internet του (ispDetails).
Δείτε: Τιμολόγια & αποδείξεις
Πώς δείχνω το PDF του παραστατικού σε προεπισκόπηση στον browser, αφού το endpoint το επιστρέφει ως λήψη (attachment);
Το endpoint του PDF (invoiceUrl / GetInvoicePdf) επιστρέφει σκόπιμα το αρχείο ως attachment, ώστε τα ERP να το κατεβάζουν και να το αποθηκεύουν· δεν υπάρχει παράμετρος (π.χ. ?preview=true) ούτε εναλλακτικό header. Για προεπισκόπηση διαβάστε το αρχείο στη δική σας πλευρά. Είτε το σερβίρετε από το backend σας με Content-Disposition: inline, είτε στο frontend το φέρνετε με fetch, το παίρνετε ως Blob και ανοίγετε ένα τοπικό object URL.
Δείτε: Υπόλοιπες κλήσεις
Πώς στέλνω τιμολόγιο τύπου 1.5 (Εκκαθάριση Πωλήσεων Τρίτων – Αμοιβή από Πωλήσεις Τρίτων);
Στέλνεται με το SendInvoices και invoiceType = 1.5, με την ίδια δομή JSON όπως κάθε τιμολόγιο (issuer, counterpart, invoiceHeader, paymentMethods, invoiceDetails, invoiceSummary, providerAdditionalInvoiceDetails). Η διαφορά είναι στις γραμμές: κάθε γραμμή δηλώνει invoiceDetailType 1 (Εκκαθάριση Πωλήσεων Τρίτων) ή 2 (Αμοιβή από Πωλήσεις Τρίτων), και η ΑΑΔΕ απαιτεί τουλάχιστον μία γραμμή από το καθένα (σφάλμα 246). Οι χαρακτηρισμοί ακολουθούν τους συνδυασμούς της ΑΑΔΕ για τον τύπο 1.5, και η σύνοψη έχει τα αθροίσματα των χαρακτηρισμών των γραμμών (εσόδων και εξόδων, όπου υπάρχουν).
Δείτε: Γραμμές & πληρωμές
Η έκδοση παραστατικού είναι σύγχρονη ή το αποτέλεσμα έρχεται με webhook;
Σύγχρονη. Το SendInvoices επιστρέφει στην ίδια κλήση το αποτέλεσμα: statusCode, MARK, UID, Authentication Code, QR και link του PDF, ή τα σφάλματα. Δεν χρειάζεται webhook. Η μόνη εξαίρεση είναι το statusCode = Offline: το παραστατικό έχει εκδοθεί και ο Πάροχος το διαβιβάζει μόλις επανέλθει η ΑΑΔΕ· το MARK το βρίσκετε μετά με RequestTransmittedDocs.
Δείτε: Πώς λειτουργεί
Ποιος στέλνει το παραστατικό με email στον λήπτη, και μπορώ να προσαρμόσω αποστολέα, θέμα και κείμενο;
Ο Πάροχος στέλνει το PDF στο providerAdditionalInvoiceDetails.additionalDetails.recipients.email, αν το συμπληρώσετε, και στις διευθύνσεις παραλαβής που επιστρέφει η ΑΑΔΕ για τον λήπτη, αν αυτός έχει δηλώσει ότι παραλαμβάνει ηλεκτρονικά. Αν δεν υπάρχει καμία από τις δύο, δεν στέλνεται email. Αποστολέας, θέμα και κείμενο είναι σταθερά. Μπορείτε παράλληλα να στέλνετε και δικό σας email από την εφαρμογή σας με το invoiceUrl.
Δείτε: SendInvoices
Μπορεί μια πλατφόρμα συνδρομών ή e-shop να εκδίδει αυτόματα παραστατικό μέσω API μετά από κάθε επιτυχή χρέωση κάρτας σε πύλη πληρωμών;
Ναι. Η πλατφόρμα σας χρεώνει την κάρτα μέσω της πύλης πληρωμών, λαμβάνει την επιβεβαίωση και μετά καλεί το SendInvoices για να εκδοθεί το παραστατικό (π.χ. 11.2 για ιδιώτη, 2.1 για επιχείρηση), χωρίς χειροκίνητη ενέργεια. Η Novus δεν συνδέεται απευθείας με την πύλη πληρωμών· τη ροή πύλη → πλατφόρμα → Provider API την υλοποιεί ο προγραμματιστής σας. Ως τρόπο πληρωμής δηλώνετε type 7 (POS / e-POS)· η υπογραφή Παρόχου (skipSignature=false) χρειάζεται μόνο όταν το τερματικό είναι «κλειδωμένο» κατά Α.1155/2023, οπότε επιβεβαιώστε αν ισχύει για την πύλη σας.
Δείτε: Πώς λειτουργεί
Δέχεται το API απευθείας τους κωδικούς της ΑΑΔΕ (τύπους παραστατικών, ΦΠΑ, χαρακτηρισμούς, τρόπους πληρωμής) και ποιους τύπους παραστατικών υποστηρίζει;
Ναι, το API δέχεται απευθείας τους επίσημους κωδικούς του myDATA: invoiceType (π.χ. 2.1, 11.2, 5.1), vatCategory, vatExemptionCategory (υποχρεωτικό όταν vatCategory = 7), incomeClassification / expensesClassification και paymentMethods[].type. Μέσω Παρόχου όμως διαβιβάζονται μόνο οι τύποι 1.1 έως 11.5· οι τύποι 12.x έως 17.x (παραστατικά λήπτη, έξοδα, εγγραφές τακτοποίησης) δεν στέλνονται ποτέ από Πάροχο. Όλοι οι κωδικοί είναι στους «Πίνακες ΑΑΔΕ» της τεκμηρίωσης και υπάρχουν έτοιμα JSON για τους βασικούς τύπους.
Δείτε: Παραστατικά
Πώς δηλώνεται το Τέλος Ανθεκτικότητας στην Κλιματική Κρίση σε καταλύματα;
Το τέλος εκδίδεται ως παραστατικό τύπου 8.2 (Τέλος ανθεκτικότητας κλιματικής κρίσης). Στη γραμμή δηλώνεται ως λοιπός φόρος με ποσό: otherTaxesPercentCategory από 20 έως 30, ανάλογα με το είδος του καταλύματος, και otherTaxesAmount = ποσό ανά διανυκτέρευση × διανυκτερεύσεις, με netValue 0, vatCategory 8 και χαρακτηρισμό category1_95. Το totalOtherTaxesAmount, το totalGrossValue και ο τρόπος πληρωμής ισούνται με το ποσό του τέλους. Υπάρχει έτοιμο JSON στα παραδείγματα του οδηγού «Τιμολόγια & αποδείξεις».
Δείτε: Τιμολόγια & αποδείξεις
Μπορώ να διαβιβάσω μέσω Παρόχου παραστατικά με παλαιότερη ημερομηνία έκδοσης, αν δεν στάλθηκαν τη σωστή ημέρα;
Όχι. Μέσω Παρόχου το issueDate πρέπει να είναι η σημερινή ημερομηνία (αλλιώς η ΑΑΔΕ απορρίπτει με σφάλμα 238), γιατί ο Πάροχος διαβιβάζει μόνο σε πραγματικό χρόνο. Η μόνη εξαίρεση είναι όταν η εφαρμογή σας δεν μπορούσε να φτάσει τον Πάροχο: τότε στέλνετε με "transmissionFailure": 1 και την αρχική ημερομηνία, αλλά μόνο μέσα σε 1 ημέρα από το issueDate. Παραστατικά που δεν στάλθηκαν ποτέ δεν διαβιβάζονται αναδρομικά, οπότε παρακολουθείτε ότι κάθε αποστολή έγινε πραγματικά και για τον χειρισμό τους συμβουλεύεστε τον λογιστή.
Δείτε: SendInvoices
Υπάρχουν έτοιμα παραδείγματα JSON για Τιμολόγιο Ενδοκοινοτικών Παραδόσεων (1.2) και Συμπληρωματικό Παραστατικό (1.6);
Στην τρέχουσα τεκμηρίωση δεν υπάρχουν έτοιμα JSON για 1.2 και 1.6 (υπάρχουν για 1.1, 2.1, 3.1, 5.1, 5.2, 8.2 και 11.x). Και τα δύο εκδίδονται με το ίδιο SendInvoices, αλλάζοντας το invoiceType και τα σχετικά πεδία· στο 1.2 ο λήπτης είναι αλλοδαπός (με name και address) και ο συνήθης χαρακτηρισμός είναι E3_561_005, ενώ στο 1.6 δεν γίνεται δεκτό το multipleConnectedMarks. Δείγματα για 1.2 και 1.6 μπορείτε να ζητήσετε από τη Novus.
Δείτε: Τιμολόγια & αποδείξεις
Μπορώ να εκδώσω μέσω του Παρόχου παραστατικό που δεν διαβιβάζεται στην ΑΑΔΕ, π.χ. για προείσπραξη σε διαδικασία tax free που γίνεται από τρίτη υπηρεσία;
Όχι. Κάθε παραστατικό που εκδίδεται μέσω του Παρόχου παίρνει MARK και διαβιβάζεται στο myDATA τη στιγμή της έκδοσης. Δεν υπάρχει «μη διαβιβαζόμενο» παραστατικό, όπως δεν υπάρχει και σε ταμειακή μηχανή. Για tax free που το διεκπεραιώνει εξωτερική υπηρεσία, το πώς τεκμηριώνεται η προείσπραξη και το πιστωτικό λιανικής για τον ΦΠΑ που επιστρέφεται τα επιβεβαιώνετε με τον λογιστή.
Δείτε: Πώς λειτουργεί
Πώς στέλνω ένα παραστατικό (π.χ. απλοποιημένο 11.3 χωρίς ΦΠΑ) ώστε το ποσό να χαρακτηρίζεται στο myDATA ως πληροφοριακό και όχι ως έσοδο;
Τον χαρακτηρισμό δεν τον ορίζει η σειρά ούτε ο Πάροχος. Προκύπτει από το incomeClassification που στέλνει η εφαρμογή σας στο SendInvoices. Στις γραμμές (invoiceDetails[].incomeClassification) στέλνετε classificationCategory = category1_95 (Λοιπά Πληροφοριακά Στοιχεία Εσόδων) χωρίς classificationType (κωδικό E3), με ποσό ίσο με το netValue. Την ίδια αλλαγή κάνετε στο invoiceSummary.incomeClassification, με ποσό το σύνολο της καθαρής αξίας. Γραμμές με πραγματικό έσοδο κρατούν τον κανονικό χαρακτηρισμό (category1_x με E3), και το ποια περίπτωση ισχύει το κρίνει ο λογιστής.