Σφάλματα

Τι σημαίνει κάθε σφάλμα και τι κάνετε.

Τι σημαίνει το σφάλμα 401 «You don't have the authority to send for this vat numbers» και πώς το διορθώνω;

Το API key είναι σωστό, αλλά ο ΑΦΜ του εκδότη (issuer.vatNumber) δεν είναι ενεργοποιημένος στον λογαριασμό σας, οπότε το παραστατικό δεν στέλνεται και δεν χρεώνεται. Στο sandbox ενεργοποιείται αυτόματα μόνο ο ΑΦΜ της εγγραφής σας, ενώ στην παραγωγή κάθε ΑΦΜ πελάτη ενεργοποιείται μετά το onboarding (provisioning.status = COMPLETED). Ελέγξτε ότι στέλνετε τον σωστό ΑΦΜ εκδότη και, αν θα έπρεπε να είναι ενεργός, επικοινωνήστε με τη Novus.

Δείτε: Περιβάλλοντα & API key

Όταν το SendInvoices επιστρέφει statusCode = Offline, πρέπει να ξαναστείλω το παραστατικό και πώς παίρνω αργότερα MARK, Authentication Code και QR;

Όχι, δεν το ξαναστέλνετε: το παραστατικό έχει εκδοθεί με UID και ο Πάροχος θα το στείλει αυτόματα στην ΑΑΔΕ όταν εκείνη επανέλθει. Αρχικά παίρνετε invoiceMark = 0, κενό authenticationCode και PDF με την ένδειξη απώλειας διασύνδεσης Παρόχου - ΑΑΔΕ. Το τελικό MARK, το Authentication Code και το νέο PDF τα παίρνετε με RequestTransmittedDocs φιλτράροντας με το uid (δεν τεκμηριώνεται webhook για αυτό). Αν χρειαστεί συσχέτιση πριν αποκτήσει MARK (π.χ. κλείσιμο τραπεζιού), χρησιμοποιήστε το UID.

Δείτε: Offline & επαναλήψεις

Πώς ελέγχω αν ένα παραστατικό Offline διαβιβάστηκε τελικά στην ΑΑΔΕ;

Με RequestTransmittedDocs και uid=<invoiceUid>. Όσο δεν έχει διαβιβαστεί, υπάρχει μία εγγραφή με mark 0. Μόλις διαβιβαστεί, εμφανίζεται και δεύτερη εγγραφή με το MARK της ΑΑΔΕ. Όσο η ΑΑΔΕ δεν απαντά, γίνονται μόνο οι έλεγχοι του Παρόχου, οπότε ένα παραστατικό με λάθος στα δεδομένα μπορεί να μη γίνει δεκτό όταν διαβιβαστεί. Αν μετά από 24 ώρες υπάρχει ακόμη μόνο η εγγραφή με mark 0, επικοινωνήστε μαζί μας με το invoiceUid.

Δείτε: Offline & επαναλήψεις

Γιατί ένα τιμολόγιο παροχής υπηρεσιών σε πελάτη εξωτερικού απορρίπτεται με το μήνυμα «Classification type E3_561_001 is forbidden ...»;

Ο κωδικός E3_561_001 αφορά πωλήσεις χονδρικής σε επιτηδευματίες εσωτερικού, και η ΑΑΔΕ δεν τον δέχεται σε παραστατικό εξωτερικού όπως το 2.2. Αλλάξτε το classificationType ανάλογα με τη χώρα του λήπτη: E3_561_005 για πελάτη σε χώρα της ΕΕ (τύπος 2.2, κατηγορία category1_3), ή E3_561_006 για πελάτη σε τρίτη χώρα, όπου ο σωστός τύπος είναι συνήθως ο 2.3. Αλλάξτε τον χαρακτηρισμό και στις γραμμές και στο invoiceSummary.

Δείτε: Χαρακτηρισμοί εσόδων / εξόδων

Γιατί απορρίπτεται το τιμολόγιο αυτοτιμολόγησης όταν στέλνω το selfPricing με την τιμή true σε εισαγωγικά;

Το selfPricing είναι boolean και στέλνεται ως JSON boolean (true), χωρίς εισαγωγικά. Με τιμή μέσα σε εισαγωγικά (string) το παραστατικό απορρίπτεται και δεν εκδίδεται. Το ίδιο ισχύει για όλα τα boolean πεδία, π.χ. isDeliveryNote και fuelInvoice.

Δείτε: SendInvoices

Γιατί παίρνω τα σφάλματα ΑΑΔΕ 207, 208 και 312, ενώ τα ποσά φαίνονται σωστά;

Τα σφάλματα 207, 208 και 312 σημαίνουν ότι τα αθροίσματα των γραμμών (καθαρή αξία, μικτή αξία, χαρακτηρισμοί) δεν ταυτίζονται με τα σύνολα του invoiceSummary. Συνήθως φταίει η στρογγυλοποίηση: απορρίπτεται ακόμη και διαφορά λίγων λεπτών, π.χ. 0,03 €. Υπολογίστε τα σύνολα αθροίζοντας τις ήδη στρογγυλεμένες τιμές των γραμμών (2 δεκαδικά), ώστε το totalNetValue, το totalGrossValue και τα ποσά των χαρακτηρισμών να συμφωνούν ακριβώς.

Δείτε: Κωδικοί σφαλμάτων ΑΑΔΕ

Τι σημαίνει το σφάλμα 202 «Invalid Greek VAT number», όταν ο πελάτης επιμένει ότι ο ΑΦΜ είναι σωστός;

Το σφάλμα το επιστρέφει η ΑΑΔΕ (myDATA), όχι ο Πάροχος, και σημαίνει ότι ο ΑΦΜ δεν είναι έγκυρος ελληνικός ΑΦΜ. Ελέγξτε για τυπογραφικό λάθος ή λάθος ψηφίο ελέγχου, π.χ. αναζητώντας τον ΑΦΜ σε μητρώο. Ο Πάροχος προωθεί τα δεδομένα όπως τα λαμβάνει και δεν διορθώνει ΑΦΜ.

Δείτε: Κωδικοί σφαλμάτων ΑΑΔΕ

Τι σημαίνει το σφάλμα HTTP 400 «The invoicesDocRequest field is required» ή «The JSON value could not be converted to …» όταν στέλνω παραστατικό;

Το σώμα του request δεν μπορεί να διαβαστεί (deserialization) με το σχήμα του API, οπότε ο Πάροχος το απορρίπτει με HTTP 400 και το παραστατικό δεν φτάνει στην ΑΑΔΕ. Η συνηθέστερη αιτία είναι πεδίο που πρέπει να είναι πίνακας αλλά στάλθηκε ως σκέτο αντικείμενο ή κενό: τα invoice, invoiceDetails, paymentMethods και incomeClassification / expensesClassification μπαίνουν πάντα μέσα σε [ ], ακόμη και με ένα στοιχείο. Το ίδιο συμβαίνει με τιμή κωδικού που δεν αναγνωρίζεται ή είναι κενή (π.χ. στον χαρακτηρισμό). Το Path του μηνύματος (π.χ. $.invoice[0].invoiceDetails) δείχνει ποιο πεδίο φταίει· διορθώνετε και ξαναστέλνετε με την ίδια σειρά/ΑΑ, αφού το παραστατικό δεν εκδόθηκε.

Δείτε: SendInvoices

Τι κάνω σε HTTP 5xx, timeout ή αποτυχία σύνδεσης, όταν δεν ξέρω αν το παραστατικό παραλήφθηκε, ώστε να μην εκδοθεί δύο φορές;

Θεωρήστε την κατάσταση άγνωστη. Πρώτα ελέγξτε με RequestTransmittedDocs (π.χ. με σειρά/ΑΑ ή UID) αν το παραστατικό υπάρχει και έχει MARK. Αν δεν υπάρχει, ξαναστείλτε το ίδιο ακριβώς payload (ίδια σειρά, ΑΑ και ημερομηνία)· αν η πρώτη αποστολή είχε περάσει, η ΑΑΔΕ επιστρέφει σφάλμα 228 με το αρχικό MARK και Authentication Code, τα οποία κρατάτε ως «ήδη εκδομένο». Μην κάνετε άμεσο retry: αφήστε εύλογη καθυστέρηση (π.χ. exponential backoff), γιατί δύο αιτήματα με διαφορά λίγων milliseconds μπορεί να παρακάμψουν τον έλεγχο διπλοτύπου της ΑΑΔΕ. Αν ο Πάροχος παραμένει απρόσιτος, εκδίδετε τοπικά και στέλνετε μέσα σε 1 ημέρα με transmissionFailure: 1.

Δείτε: Offline & επαναλήψεις

Γιατί παίρνω HTTP 401 Unauthorized στο SendInvoices της παραγωγής, ενώ το ίδιο API key δουλεύει σε άλλη εγκατάσταση; Χρειάζομαι κλειδί ανά πελάτη;

Δεν χρειάζεστε κλειδί ανά πελάτη: ένα API key εξυπηρετεί όλους τους ενεργοποιημένους ΑΦΜ σας, και ο πελάτης προκύπτει από το issuer.vatNumber. Ένα 401 χωρίς μήνυμα errors σημαίνει ότι το header API-KEY λείπει ή δεν φτάνει σωστά, ότι το κλειδί είναι λάθος ή ανενεργό, ή ότι στέλνετε κλειδί Sandbox σε Production (ή ανάποδα). Αν δεν είναι ενεργοποιημένος ο ΑΦΜ του εκδότη, το 401 έρχεται με errors «You don't have the authority to send for this vat numbers ...». Ελέγξτε τη ρύθμιση της συγκεκριμένης εγκατάστασης (header, URL περιβάλλοντος, κενά ή κρυφοί χαρακτήρες στο κλειδί). Αν το πρόβλημα μένει, στείλτε στη Novus το JSON του request και του response.

Δείτε: Περιβάλλοντα & API key