Onboarding & πελάτες¶
Ενεργοποίηση πελατών, συμβάσεις, Δήλωση Παρόχου.
Ποια είναι η διαδικασία για να ενεργοποιήσω έναν νέο πελάτη (ΑΦΜ) ώστε να εκδίδει μέσω της εφαρμογής μου;
Με το Onboarding API στέλνετε POST /api/v1/requests με τα στοιχεία του πελάτη: επωνυμία, ΑΦΜ, ΔΟΥ, transactionTypes (B2B/B2C), διεύθυνση, email και τηλέφωνο επικοινωνίας, νόμιμο εκπρόσωπο και, για B2C, ispDetails. Ο πελάτης λαμβάνει με email τη σύμβαση και την ανεβάζει υπογεγραμμένη (ή την ανεβάζετε εσείς με signed-contract), η Novus την ελέγχει και με την έγκριση ο ΑΦΜ ενεργοποιείται στο κλειδί σας και υποβάλλεται η Δήλωση Παρόχου, που ο πελάτης αποδέχεται στο myAADE μέσα σε 10 ημέρες. Απαιτείται επίσης η εξουσιοδότηση της Novus ως Παρόχου από τον πελάτη στο myAADE. Εκδίδετε για τον πελάτη όταν provisioning.status = COMPLETED· εναλλακτικά η διαδικασία γίνεται από το portal.
Μπορώ να αυτοματοποιήσω την αίτηση ενεργοποίησης ενός ΑΦΜ και να ενημερώνομαι αυτόματα για την κατάστασή της;
Ναι, με το Onboarding API: η αίτηση δημιουργείται με POST /api/v1/requests, η κατάσταση (PENDING_SIGNATURE, UNDER_REVIEW, ACTION_REQUIRED, APPROVED, REJECTED, CANCELLED) διαβάζεται με GET /api/v1/requests/{requestId} και το ιστορικό με /history. Για να αποφύγετε το polling, δηλώστε webhook με POST /api/v1/webhooks για τα events request.status_changed και request.provisioned, και επαληθεύετε πάντα την υπογραφή X-Novus-Signature. Πριν ενεργοποιήσετε την έκδοση για τον πελάτη, επιβεβαιώνετε την κατάσταση με GET.
Δείτε: Webhooks
Ποιες μορφές υπογραφής γίνονται δεκτές στη σύμβαση του πελάτη και μπορώ να χειριστώ την υπογραφή μέσα από την εφαρμογή μου;
Γίνεται δεκτή κάθε ευανάγνωστη υπογραφή: σκαναρισμένη ιδιόχειρη, μέσω gov.gr ή ψηφιακή. Το αρχείο πρέπει να είναι PDF έως 15 MB, με όλες τις σελίδες όρθιες και καθαρές· αλλιώς η αίτηση πάει σε ACTION_REQUIRED. Μπορείτε να κατεβάσετε τη σύμβαση με GET /api/v1/requests/{requestId}/contract, να τη δείξετε στον πελάτη και να ανεβάσετε εσείς την υπογεγραμμένη με POST /api/v1/requests/{requestId}/signed-contract (πεδίο contractFile). Ο σύνδεσμος του email είναι εναλλακτική, όχι υποχρεωτικό βήμα, και για τον πελάτη η πιο απλή λύση είναι συνήθως το gov.gr.
Δείτε: Onboarding API: endpoints
Ποιο είναι το μέγιστο επιτρεπόμενο μέγεθος αρχείου για την υπογεγραμμένη σύμβαση;
Η υπογεγραμμένη σύμβαση πρέπει να είναι πραγματικό PDF (όχι κατεστραμμένο ή κλειδωμένο με κωδικό) και έως 15 MB. Πάνω από αυτό το Onboarding API επιστρέφει 413 FILE_TOO_LARGE. Αν ένα σκαναρισμένο αρχείο ξεπερνά το όριο, σκανάρετε με χαμηλότερη ανάλυση ή συμπιέστε το PDF.
Δείτε: Onboarding API: endpoints
Χρειάζεται ο πελάτης δικά του διαπιστευτήρια myDATA ή εξουσιοδότηση προς τον Πάροχο για να εκδίδει μέσω της εφαρμογής μου;
Δεν χρειάζονται τα διαπιστευτήρια myDATA (user id / subscription key) του πελάτη. Απαιτούνται η σύμβαση με τη Novus, η εξουσιοδότηση της Novus ως Παρόχου από τον πελάτη στο myAADE και η Δήλωση Παρόχου, που την υποβάλλει η Novus μετά την έγκριση και ο πελάτης την αποδέχεται στο myAADE μέσα σε 10 ημέρες (αλλιώς θεωρείται αποδεκτή σιωπηρά). Η εξουσιοδότηση εξακολουθεί να απαιτείται και όταν η ενεργοποίηση γίνεται με το Onboarding API.
Μπορεί ένας πελάτης που έχει ήδη εξουσιοδοτήσει άλλο Πάροχο να χρησιμοποιεί ταυτόχρονα και τη Novus;
Ναι, μια επιχείρηση μπορεί να χρησιμοποιεί περισσότερους από έναν Παρόχους. Για τη Novus χρειάζονται κανονικά σύμβαση, εξουσιοδότηση και Δήλωση Παρόχου. Αν ο πελάτης έχει ήδη σύμβαση με τη Novus μέσω άλλου software house, το Onboarding API δημιουργεί αίτημα LINK_EXISTING χωρίς νέα σύμβαση.
Πόσο χρόνο παίρνει η ενεργοποίηση ενός νέου πελάτη μέχρι να μπορεί να εκδίδει;
Εξαρτάται κυρίως από το πόσο γρήγορα ο πελάτης υπογράψει και ανεβάσει τη σύμβαση και κάνει την εξουσιοδότηση. Από τη στιγμή που υπάρχει υπογεγραμμένη σύμβαση, ο έλεγχος της Novus (UNDER_REVIEW) ολοκληρώνεται συνήθως μέσα σε 1 εργάσιμη, συχνά σε λίγες ώρες. Ο πελάτης μπορεί να εκδίδει όταν η αίτηση είναι APPROVED και provisioning.status = COMPLETED.
Για ποιους λόγους μπορεί να μη γίνει δεκτή η υπογεγραμμένη σύμβαση Παρόχου ενός πελάτη;
Η σύμβαση πρέπει να είναι πλήρης: συμπληρωμένα κανονικά όλα τα στοιχεία (όχι μόνο με σφραγίδα), με ημερομηνία και αριθμό σύμβασης, όλες οι σελίδες όρθιες και ευανάγνωστες, σε PDF έως 15 MB. Γίνεται δεκτή σκαναρισμένη ιδιόχειρη, gov.gr ή ψηφιακή υπογραφή. Αν η σύμβαση δεν γίνει δεκτή, η αίτηση περνά σε ACTION_REQUIRED με την αιτία στο message και ανεβάζετε νέα υπογεγραμμένη σύμβαση. Με το Onboarding API η σύμβαση παράγεται ήδη συμπληρωμένη με αριθμό και ημερομηνία, κάτι που αποφεύγει τέτοια λάθη.
Τι σημαίνει το μήνυμα «the requested contract is not readable» σε αίτηση ενεργοποίησης πελάτη;
Η υπογεγραμμένη σύμβαση δεν έγινε δεκτή στον έλεγχο της Novus και η αίτηση πέρασε σε ACTION_REQUIRED, με την αιτία στο message. Συνήθως φταίει το αρχείο: σελίδες ανάποδα ή στραβά, θολό σκανάρισμα ή σελίδες που λείπουν. Ανεβάστε νέο PDF με όλες τις σελίδες όρθιες και καθαρές (έως 15 MB), με POST /api/v1/requests/{requestId}/signed-contract ή από το link που έλαβε ο πελάτης, και η αίτηση επιστρέφει σε UNDER_REVIEW.
Πώς ξέρω αν ο πελάτης δήλωσε στη σύμβαση λιανική (B2C), χονδρική (B2B) ή και τα δύο;
Με το Onboarding API τα είδη συναλλαγών τα δηλώνετε εσείς στην αίτηση, στο companyDetails.transactionTypes (B2B, B2C ή και τα δύο· το B2G δεν γίνεται δεκτό), και η σύμβαση παράγεται με βάση αυτά. Για B2C απαιτείται επιπλέον το ispDetails. Συνεννοηθείτε με τον πελάτη πριν την αίτηση, ώστε οι ρυθμίσεις της εφαρμογής σας να συμφωνούν με όσα δηλώνονται στη σύμβαση και στο myDATA.
Δείτε: Onboarding API: endpoints
Είναι υποχρεωτικό να συμπληρωθεί το Παράρτημα Α της σύμβασης Παρόχου;
Ναι, όταν ο πελάτης εκδίδει παραστατικά λιανικής (B2C), είτε μόνο λιανική είτε λιανική και χονδρική, γιατί το απαιτεί η ΑΑΔΕ. Στο Onboarding API η αντίστοιχη πληροφορία είναι ο πάροχος internet του πελάτη (ispDetails.providerName, contractNumber, contractDate), υποχρεωτικός όταν τα transactionTypes περιέχουν B2C· για μόνο B2B παραλείπεται.
Πρέπει κάθε πελάτης (ΑΦΜ) να υπογράψει δική του σύμβαση με τη Novus, ακόμη κι αν τον εξυπηρετώ ως μεταπωλητής;
Ναι. Η σύμβαση είναι μεταξύ Novus και πελάτη και υπογράφεται από τον νόμιμο εκπρόσωπο κάθε επιχείρησης· μαζί απαιτούνται η εξουσιοδότηση της Novus στο myAADE και η Δήλωση Παρόχου. Σύμβαση και Δήλωση γίνονται μία φορά ανά πελάτη, όσα software houses κι αν τον εξυπηρετούν. Το μοντέλο μεταπώλησης αφορά τα credits, όχι τη σύμβαση.
Τι είναι το email «Οδηγίες διασύνδεσης Παρόχου Ηλεκτρονικής τιμολόγησης» που λαμβάνει ο πελάτης, και τι πρέπει να κάνει;
Είναι μέρος της ενεργοποίησης του πελάτη στον Πάροχο. Στέλνεται ως απάντηση σε αίτημα διασύνδεσης και περιέχει σύνδεσμο στο portal για να ολοκληρωθεί η διασύνδεση, δηλαδή η σύμβαση με τη Novus. Ο πελάτης ακολουθεί τον σύνδεσμο και ολοκληρώνει τη διαδικασία· αν δεν ζήτησε υπηρεσίες ηλεκτρονικής τιμολόγησης, αγνοεί το μήνυμα. Μετά την έγκριση ο ΑΦΜ ενεργοποιείται, και ο πελάτης πρέπει να αποδεχθεί τη Δήλωση Παρόχου στο myAADE μέσα σε 10 ημέρες.
Γιατί η αίτηση για πελάτη με συναλλαγές B2C ζητά στοιχεία «παρόχου» (όνομα, αριθμό και ημερομηνία συμβολαίου) και τι πρέπει να συμπληρώσω;
Όταν ο πελάτης δηλώνει συναλλαγές B2C (λιανική), η ΑΑΔΕ απαιτεί τα στοιχεία του παρόχου internet του (εναλλακτικός πάροχος σύνδεσης), όχι της Novus ως Παρόχου τιμολόγησης. Στο Onboarding API τα δίνετε στο ispDetails με providerName, contractNumber και contractDate (όχι μελλοντική)· αν ο πελάτης κάνει μόνο B2B, το ispDetails παραλείπεται. Επειδή η σύμβαση παράγεται ήδη συμπληρωμένη, πρέπει να έχετε αυτά τα στοιχεία πριν κάνετε την αίτηση. Αίτηση με B2C χωρίς στοιχεία παρόχου internet δεν προχωρά.
Δείτε: Onboarding API: endpoints
Πελάτης που ήδη εκδίδει μέσω Novus μόνο λιανική (B2C) θέλει να προσθέσει και χονδρική (B2B) ή να δηλώσει ξανά τον Πάροχο: τι πρέπει να γίνει;
Χρειάζεται νέα σύμβαση (από το portal) που να περιλαμβάνει όλες τις συναλλαγές, και αλλαγή της δήλωσης Παρόχου στο myDATA: ο πελάτης, συνήθως μέσω του λογιστή του, ανακαλεί την υπάρχουσα δήλωση ορίζοντας ως ημέρα λήξης την ημέρα της αλλαγής (η ανάκληση υποβάλλεται το αργότερο 10 ημέρες μετά). Στη συνέχεια η Novus, με βάση τη νέα σύμβαση, υποβάλλει νέα Δήλωση Έναρξης με όλες τις ενεργές συναλλαγές (υφιστάμενες και νέες), την οποία ο πελάτης εγκρίνει στο myAADE. Αν η νέα αίτηση επιστρέφει 409 CLIENT_ALREADY_LINKED, ο πελάτης πρέπει πρώτα να αφαιρεθεί από τον λογαριασμό σας και να γίνει νέα αίτηση, με την ανάκληση και την αποδοχή από τη Novus την ίδια ημέρα. Πριν από κάθε αλλαγή ο πελάτης καλό είναι να συμβουλευτεί τον λογιστή του.
Δείτε: Onboarding API: endpoints
Ο πελάτης ζητά τον αριθμό και την ημερομηνία της σύμβασής του με τον Πάροχο για να δηλώσει τον Πάροχο στην ΑΑΔΕ. Πού τα βρίσκει;
Τη Δήλωση Παρόχου στην ΑΑΔΕ την υποβάλλει η Novus μετά την έγκριση της σύμβασης. Ο πελάτης απλώς την αποδέχεται στο myAADE μέσα σε 10 ημέρες, αλλιώς θεωρείται σιωπηρά αποδεκτή. Ο αριθμός και η ημερομηνία της σύμβασης υπάρχουν στο contract (contractNumber, contractDate) της αίτησης στο Onboarding API, και το PDF το κατεβάζετε με GET /api/v1/requests/{requestId}/contract. Για παλαιότερες συμβάσεις που δεν έγιναν μέσω API, το αντίγραφο το ζητάτε από τη Novus.
Δείτε: Onboarding API: endpoints
Σε ατομική επιχείρηση ή αγρότη, τι συμπληρώνω στα πεδία administrator της αίτησης onboarding;
Στην ατομική επιχείρηση ο νόμιμος εκπρόσωπος είναι ο ίδιος ο επιχειρηματίας. Στέλνετε στο administrator.fullName το ονοματεπώνυμό του και στο administrator.vatNumber τον ίδιο ΑΦΜ με το companyDetails.vatNumber. Δεν υπάρχει έλεγχος που να απορρίπτει τους δύο ίδιους ΑΦΜ· αρκεί ο ΑΦΜ να έχει σωστό check digit.
Δείτε: Onboarding API: endpoints
Αν ο πελάτης έχει ήδη σύμβαση Novus μέσω άλλου software house (LINK_EXISTING), κόβεται η σύνδεσή του με εκείνο μετά την έγκριση;
Όχι. Ένας ΑΦΜ μπορεί να συνδέεται ταυτόχρονα με περισσότερα software houses, ενώ η σύμβαση και η Δήλωση Παρόχου γίνονται μία φορά ανά πελάτη. Με την έγκριση ενός αιτήματος LINK_EXISTING ο ΑΦΜ απλώς προστίθεται στο δικό σας API key, χωρίς νέα υπογραφή, και η σύνδεση με το προηγούμενο software house μένει ενεργή. Ο πελάτης μπορεί να εκδίδει και από τις δύο εφαρμογές.
Μπορώ να απενεργοποιήσω ή να ξαναστείλω το αυτόματο email της σύμβασης προς τον πελάτη, και λήγει ο σύνδεσμός του;
Το email με τη σύμβαση και τον σύνδεσμο ανεβάσματος στέλνεται πάντα στο contactInfo.email και δεν απενεργοποιείται, γιατί η σύμβαση συνάπτεται μεταξύ Novus και πελάτη. Ο σύνδεσμος δεν λήγει και δείχνει πάντα την τρέχουσα κατάσταση της αίτησης. Επαναποστολή δεν προβλέπεται: αν χρειαστεί νέο email, ακυρώνετε την αίτηση με DELETE /api/v1/requests/{requestId} (μόνο πριν την έγκριση) και δημιουργείτε νέα, με νέο Idempotency-Key.
Πώς δοκιμάζω τη ροή onboarding στο δοκιμαστικό περιβάλλον; Γίνεται πραγματική σύμβαση ή Δήλωση Παρόχου και στέλνονται emails;
Στο δοκιμαστικό δεν δημιουργείται πραγματική σύμβαση ούτε υποβάλλεται Δήλωση Παρόχου. Μπορείτε να χρησιμοποιήσετε πραγματικούς ΑΦΜ ή οποιονδήποτε εννιαψήφιο με σωστό check digit. Η ροή: δημιουργείτε αίτηση, κατεβάζετε το PDF, ανεβάζετε ένα υπογεγραμμένο PDF, στέλνετε στη Novus το requestId για να την εγκρίνει και παρακολουθείτε το provisioning μέχρι COMPLETED. Δοκιμάστε και τα σφάλματα 409 DUPLICATE_OPEN_REQUEST και 422. Τα emails στέλνονται κανονικά, οπότε στο contactInfo.email βάζετε μόνο δικές σας διευθύνσεις.
Από πότε μπορεί να εκδίδει ο νέος πελάτης: με provisioning.status = COMPLETED ή πρέπει να περιμένω να γίνει αποδεκτή η Δήλωση Παρόχου;
Μόλις το provisioning.status γίνει COMPLETED (ή λάβετε το webhook request.provisioned), ο ΑΦΜ είναι ενεργός στο API key σας και εκδίδετε κανονικά μέσω του Provider API. Δεν χρειάζεται να περιμένετε το aadeStatement.status να γίνει ACCEPTED· αρκεί το SUBMITTED. Την αποδοχή στο myAADE την κάνει παράλληλα ο πελάτης. Αν δεν την κάνει, η δήλωση θεωρείται αποδεκτή μετά από 10 ημέρες (PRESUMED_ACCEPTED).
Δείτε: Onboarding API: endpoints
Τι πρέπει να κάνει η εφαρμογή μου όταν λάβει το webhook client.statement_recalled;
Προς το παρόν η Novus συνιστά να μη σταματάτε αυτόματα την έκδοση με βάση αυτό το event, γιατί η ΑΑΔΕ διαμορφώνει ακόμη τη διαδικασία της ανάκλησης. Από την πλευρά της Novus, ανάκληση γίνεται όταν αλλάζει ουσιωδώς το είδος των συναλλαγών του πελάτη (π.χ. σε πελάτη μόνο B2B προστίθεται B2C). Τότε ανακαλείται η παλιά δήλωση και υποβάλλεται νέα, άρα το event δεν δείχνει από μόνο του πρόβλημα. Επιβεβαιώνετε πάντα την κατάσταση με GET /api/v1/requests/{requestId} και περιμένετε οδηγία της Novus.
Δείτε: Webhooks
Πώς αποσυνδέεται ένας ενεργός πελάτης από το software house μου μετά το APPROVED;
Μετά την έγκριση η αίτηση δεν ακυρώνεται από το API (DELETE επιστρέφει 409 INVALID_TRANSITION). Η αποσύνδεση γίνεται μόνο σε συνεννόηση με τη Novus, γιατί έχει συμβατικές συνέπειες. Αφαιρεί μόνο τη δική σας σύνδεση: δεν ακυρώνει τη σύμβαση του πελάτη με τη Novus ούτε ανακαλεί τη Δήλωση Παρόχου, αν ο πελάτης συνεχίζει μέσω άλλου software house. Αν ένας πελάτης έρχεται σε εσάς από άλλο software house, στέλνετε απλώς αίτηση και παίρνετε LINK_EXISTING.
Δείτε: Onboarding API: endpoints
Ο λογιστής του πελάτη λέει ότι λείπουν δηλώσεις παρόχου στο myAADE, ενώ ο πελάτης εκδίδει μέσω Novus. Ποιος υποβάλλει τι;
Για κάθε ΑΦΜ εκδότη χρειάζονται τρία πράγματα: σύμβαση με τη Novus, εξουσιοδότηση της Novus ως Παρόχου από τον ίδιο τον πελάτη στο myAADE, και Δήλωση Παρόχου στην ΑΑΔΕ (Α.1112/2025). Το δικό του μέρος το κάνει ο πελάτης όταν ξεκινά να χρησιμοποιεί τον Πάροχο. Τη Δήλωση Παρόχου την υποβάλλει η Novus μόνο αφού ο ΑΦΜ ενεργοποιηθεί με δική του σύμβαση, από το portal ή το Onboarding API, και ο πελάτης την αποδέχεται στο myAADE μέσα σε 10 ημέρες. Αν τον πελάτη τον εξυπηρετεί software house, η διαδικασία γίνεται μέσω αυτού.
Λειτουργεί το API και για πελάτες που είχα ενεργοποιήσει πριν αρχίσω να χρησιμοποιώ το Onboarding API;
Κάθε ΑΦΜ που είναι ήδη ενεργός στο API key σας εκδίδει κανονικά μέσω του Provider API, όπως κι αν ενεργοποιήθηκε. Αν στείλετε αίτηση στο Onboarding API για ΑΦΜ που είναι ήδη ενεργός στο κλειδί σας, παίρνετε 409 CLIENT_ALREADY_LINKED· δεν χρειάζεται νέα αίτηση.
Δείτε: Περιβάλλοντα & API key
Πώς μπορεί ο πελάτης ή ο λογιστής του να επιβεβαιώσει ότι η Novus Conceptus είναι αδειοδοτημένος Πάροχος Ηλεκτρονικής Τιμολόγησης της ΑΑΔΕ;
Η Novus Conceptus είναι αδειοδοτημένος Πάροχος Ηλεκτρονικής Τιμολόγησης (ΥΠΑΗΕΣ) με κωδικό Παρόχου 005. Βρίσκεται στη δημόσια λίστα αδειοδοτημένων παρόχων στον ιστότοπο της ΑΑΔΕ, όπου μπορεί να την επαληθεύσει ο λογιστής. Τα στοιχεία της άδειας (αριθμός, ημερομηνία αδειοδότησης και ανανέωσης) υπάρχουν στην ενότητα «Ποιοι είμαστε» της τεκμηρίωσης.
Δείτε: Εκδίδετε παραστατικά από την εφαρμογή σας, με μία κλήση