Onboarding API: πώς λειτουργεί

Με το Onboarding API ενεργοποιείτε νέους πελάτες (ΑΦΜ) στο API key σας χωρίς email και χαρτιά. Στέλνετε τα στοιχεία του πελάτη, ο πελάτης υπογράφει τη σύμβαση, η Novus εγκρίνει, και το σύστημα ολοκληρώνει μόνο του την ενεργοποίηση και τη Δήλωση Παρόχου στην ΑΑΔΕ.

sequenceDiagram
    autonumber
    participant SH as Εσείς (software house)
    participant NP as Novus Onboarding API
    participant CL as Πελάτης
    participant NV as Novus (έλεγχος)
    participant AADE as ΑΑΔΕ
    SH->>NP: POST /api/v1/requests (στοιχεία πελάτη)
    NP-->>SH: requestId, status PENDING_SIGNATURE
    NP-)CL: Email με τη σύμβαση (PDF) και link ανεβάσματος
    CL->>NP: Ανεβάζει την υπογεγραμμένη σύμβαση (ή εσείς: POST …/signed-contract)
    NP-->>SH: status UNDER_REVIEW (webhook)
    NV->>NP: Έγκριση (ή ACTION_REQUIRED με αιτιολογία)
    NP->>NP: Ενεργοποίηση ΑΦΜ στο API key σας, αρχειοθέτηση σύμβασης
    NP->>AADE: Δήλωση Παρόχου
    NP-->>SH: status APPROVED, provisioning COMPLETED (webhook)
    NP-)CL: Email: «αποδεχθείτε τη δήλωση στο myAADE εντός 10 ημερών»

Οι καταστάσεις ενός αιτήματος

Status	Σημαίνει	Τι κάνετε
PENDING_SIGNATURE	Η σύμβαση παράχθηκε και στάλθηκε στον πελάτη.	Περιμένετε την υπογραφή, ή ανεβάστε την εσείς.
UNDER_REVIEW	Υπάρχει υπογεγραμμένη σύμβαση και την ελέγχει η Novus.	Τίποτα. Συνήθως ολοκληρώνεται σε 1 εργάσιμη.
ACTION_REQUIRED	Η σύμβαση δεν έγινε δεκτή (π.χ. δεν διαβάζεται). Η αιτία είναι στο message.	Ανεβάστε νέα υπογεγραμμένη σύμβαση.
APPROVED	Εγκρίθηκε. Η τεχνική ολοκλήρωση φαίνεται στο provisioning.	Όταν provisioning.status = COMPLETED, εκδίδετε κανονικά για αυτόν τον ΑΦΜ.
REJECTED	Απορρίφθηκε. Τελική κατάσταση.	Δείτε το message.
CANCELLED	Ακυρώθηκε από εσάς ή από τη Novus. Τελική κατάσταση.	Αν χρειάζεται, κάντε νέο αίτημα.

stateDiagram-v2
    [*] --> PENDING_SIGNATURE: NEW_CONTRACT
    [*] --> UNDER_REVIEW: LINK_EXISTING
    PENDING_SIGNATURE --> UNDER_REVIEW: υπογεγραμμένη σύμβαση
    UNDER_REVIEW --> ACTION_REQUIRED: η Novus ζητά διόρθωση
    ACTION_REQUIRED --> UNDER_REVIEW: νέα σύμβαση
    UNDER_REVIEW --> APPROVED
    UNDER_REVIEW --> REJECTED
    PENDING_SIGNATURE --> CANCELLED
    ACTION_REQUIRED --> CANCELLED
    UNDER_REVIEW --> CANCELLED

Δύο είδη αιτήματος: το αποφασίζει το σύστημα

requestType	Πότε	Σύμβαση;
NEW_CONTRACT	Ο ΑΦΜ δεν έχει σύμβαση με τη Novus.	Ναι. Ο πελάτης υπογράφει.
LINK_EXISTING	Ο ΑΦΜ έχει ήδη σύμβαση, π.χ. μέσω άλλου software house.	Όχι. Γίνεται μόνο η σύνδεση με το δικό σας API key, μετά από έγκριση.

Η σύμβαση και η Δήλωση Παρόχου γίνονται μία φορά ανά πελάτη, όσα software houses κι αν τον εξυπηρετούν.

Η σύμβαση

• Παράγεται αυτόματα, με τα στοιχεία του αιτήματος, και είναι ήδη υπογεγραμμένη από τη Novus.
• Στέλνεται στο contactInfo.email του πελάτη μαζί με link ανεβάσματος. Το email στέλνεται πάντα, γιατί η σύμβαση είναι μεταξύ Novus και πελάτη.
• Γίνεται δεκτή κάθε ευανάγνωστη υπογραφή: σκαναρισμένη ιδιόχειρη, μέσω gov.gr ή ψηφιακή. Πρέπει να περιλαμβάνονται όλες οι σελίδες, όρθιες και καθαρές. Μόνο PDF, έως 15 MB.
• Αν ο πελάτης κάνει συναλλαγές B2C, το αίτημα πρέπει να έχει και τον πάροχο internet του (ispDetails). Το απαιτεί η ΑΑΔΕ.

Μετά την έγκριση

1. Ο ΑΦΜ ενεργοποιείται στο API key σας και μπορείτε να εκδίδετε.
2. Η Novus στέλνει Δήλωση Παρόχου στην ΑΑΔΕ. Ο πελάτης πρέπει να την αποδεχθεί στο myAADE μέσα σε 10 ημέρες. Αλλιώς θεωρείται αποδεκτή σιωπηρά (Α.1112/2025).
3. Διακοπή συνεργασίας μετά την έγκριση γίνεται μόνο μέσω της Novus.

Στο Sandbox

Το Sandbox είναι απομονωμένο: δεν στέλνεται τίποτα στην ΑΑΔΕ, δεν φεύγουν emails και δεν δημιουργείται πραγματική σύμβαση. Μπορείτε να δοκιμάσετε και με πραγματικούς ΑΦΜ. Για να περάσει ένα δοκιμαστικό αίτημα σε APPROVED, στείλτε μας το requestId.

Επόμενα

• Όλες οι κλήσεις: Endpoints
• Ειδοποιήσεις σε πραγματικό χρόνο: Webhooks
• Για την εφαρμογή σας: OpenAPI (YAML) · Postman. Στο Postman, βάλτε το apiKey στις Variables της collection και τρέξτε τον φάκελο «1. Ροή onboarding» με τη σειρά.