Onboarding & clients¶
Client activation, contracts, Provider declaration.
What is the process to activate a new client (VAT number, ΑΦΜ) so that they can issue documents through my application?
With the Onboarding API you send POST /api/v1/requests with the client's details: legal name, VAT number, tax office (ΔΟΥ), transactionTypes (B2B/B2C), address, contact email and phone, legal representative and, for B2C, ispDetails. The client receives the contract by email and uploads it signed (or you upload it with signed-contract). Novus reviews it. On approval, the VAT number is activated on your key and the Provider declaration is submitted, which the client accepts in myAADE within 10 days. The client must also authorize Novus as their certified e-invoicing provider in myAADE. You issue for the client when provisioning.status = COMPLETED. You can also do the whole process from the portal.
Can I automate the activation request for a VAT number and get automatic updates on its status?
Yes, with the Onboarding API: you create the request with POST /api/v1/requests, read the status (PENDING_SIGNATURE, UNDER_REVIEW, ACTION_REQUIRED, APPROVED, REJECTED, CANCELLED) with GET /api/v1/requests/{requestId} and the history with /history. To avoid polling, register a webhook with POST /api/v1/webhooks for the request.status_changed and request.provisioned events, and always verify the X-Novus-Signature signature. Before you enable issuing for the client, confirm the status with GET.
See: Webhooks
Which signature types are accepted on the client's contract, and can I handle signing inside my application?
Any legible signature is accepted: a scanned handwritten signature, a gov.gr signature or a digital signature. The file must be a PDF of up to 15 MB, with all pages upright and clear; otherwise the request goes to ACTION_REQUIRED. You can download the contract with GET /api/v1/requests/{requestId}/contract, show it to the client, and upload the signed contract yourself with POST /api/v1/requests/{requestId}/signed-contract (field contractFile). The link in the email is an alternative, not a required step. For the client, gov.gr is usually the simplest option.
What is the maximum file size for the signed contract?
The signed contract must be a real PDF (not corrupted or password-protected) of up to 15 MB. Above that, the Onboarding API returns 413 FILE_TOO_LARGE. If a scanned file is over the limit, scan at a lower resolution or compress the PDF.
Does the client need their own myDATA credentials, or an authorization to the Provider, to issue through my application?
The client's myDATA credentials (user id / subscription key) are not needed. What is required: the contract with Novus, the client's authorization of Novus as their Provider in myAADE, and the Provider declaration, which Novus submits after approval and the client accepts in myAADE within 10 days (otherwise it is deemed accepted). The authorization is still required when activation goes through the Onboarding API.
Can a client who has already authorized another Provider also use Novus at the same time?
Yes, a business can use more than one Provider. For Novus, the contract, the authorization and the Provider declaration are needed as usual. If the client already has a contract with Novus through another software house, the Onboarding API creates a LINK_EXISTING request, with no new contract.
How long does it take to activate a new client until they can issue documents?
It depends mainly on how fast the client signs and uploads the contract and grants the authorization. Once there is a signed contract, the Novus review (UNDER_REVIEW) usually takes up to 1 business day, often a few hours. The client can issue when the request is APPROVED and provisioning.status = COMPLETED.
Why might a client's signed Provider contract be rejected?
The contract must be complete: all details properly filled in (not just stamped), with the contract date and number, all pages upright and legible, as a PDF of up to 15 MB. A scanned handwritten, gov.gr or digital signature is accepted. If the contract is not accepted, the request moves to ACTION_REQUIRED with the reason in message, and you upload a new signed contract. With the Onboarding API, the contract is generated already filled in with its number and date, which avoids such errors.
What does the message 'the requested contract is not readable' mean on a client activation request?
The signed contract did not pass the Novus review, and the request moved to ACTION_REQUIRED, with the reason in message. The file is usually the problem: pages upside down or skewed, a blurry scan, or missing pages. Upload a new PDF with all pages upright and clear (up to 15 MB), with POST /api/v1/requests/{requestId}/signed-contract or from the link the client received, and the request returns to UNDER_REVIEW.
How do I know whether the client declared retail (B2C), wholesale (B2B) or both in the contract?
With the Onboarding API, you declare the transaction types yourself in the request, in companyDetails.transactionTypes (B2B, B2C or both; B2G is not accepted), and the contract is generated from them. For B2C, ispDetails is also required. Agree with the client before the request, so that your application's settings match what is declared in the contract and in myDATA.
Is it mandatory to fill in Annex A of the Provider contract?
Yes, when the client issues retail (B2C) documents, either retail only or retail and wholesale, because AADE requires it. In the Onboarding API, the matching information is the client's internet service provider (ispDetails.providerName, contractNumber, contractDate), which is required when transactionTypes includes B2C. For B2B only, you leave it out.
Must each client (VAT number) sign their own contract with Novus, even if I serve them as a reseller?
Yes. The contract is between Novus and the client and is signed by the legal representative of each business. The authorization of Novus in myAADE and the Provider declaration are also required. The contract and the declaration are done once per client, no matter how many software houses serve them. The reseller model concerns credits, not the contract.
What is the email 'Οδηγίες διασύνδεσης Παρόχου Ηλεκτρονικής τιμολόγησης' (e-invoicing provider connection instructions) that the client receives, and what should they do?
It is part of the client's activation with the Provider. It is sent in response to a connection request and contains a link to the portal to complete the connection, that is, the contract with Novus. The client follows the link and completes the process. If they did not ask for e-invoicing services, they ignore the message. After approval the VAT number is activated, and the client must accept the Provider declaration in myAADE within 10 days.
Why does the request for a client with B2C sales ask for 'provider' details (name, contract number and date), and what should I fill in?
When the client declares B2C (retail) sales, AADE requires the details of their internet service provider (alternative connection provider), not of Novus as the e-invoicing provider. In the Onboarding API you give them in ispDetails with providerName, contractNumber and contractDate (not in the future). If the client only does B2B, you leave out ispDetails. Because the contract is generated already filled in, you must have these details before you make the request. A B2C request without internet provider details does not proceed.
A client who already issues retail (B2C) only through Novus wants to add wholesale (B2B) or declare the Provider again: what needs to happen?
A new contract (from the portal) that covers all transaction types is needed, and a change to the Provider declaration in myDATA. The client, usually through their accountant, revokes the existing declaration with the day of the change as its end date (the revocation must be submitted no later than 10 days after). Then Novus, based on the new contract, submits a new start declaration with all active transaction types (existing and new), which the client approves in myAADE. If the new request returns 409 CLIENT_ALREADY_LINKED, the client must first be removed from your account and a new request made, with the revocation and the acceptance by Novus on the same day. Before any change, the client should consult their accountant.
The client asks for the number and date of their contract with the Provider, to declare the Provider to AADE. Where do they find them?
Novus submits the Provider declaration to AADE after the contract is approved. The client only accepts it in myAADE within 10 days; otherwise it is deemed accepted. The contract number and date are in the contract (contractNumber, contractDate) of the request in the Onboarding API, and you download the PDF with GET /api/v1/requests/{requestId}/contract. For older contracts not made through the API, request a copy from Novus.
For a sole proprietor or a farmer, what do I fill in the administrator fields of the onboarding request?
For a sole proprietor, the legal representative is the business owner. Send their full name in administrator.fullName, and in administrator.vatNumber the same VAT number as in companyDetails.vatNumber. No check rejects two identical VAT numbers; the VAT number just needs a valid check digit.
If the client already has a Novus contract through another software house (LINK_EXISTING), is their link with that software house cut after approval?
No. A VAT number can be linked to several software houses at the same time, while the contract and the Provider declaration are done once per client. When a LINK_EXISTING request is approved, the VAT number is simply added to your API key, with no new signature, and the link with the previous software house stays active. The client can issue from both applications.
Can I disable or resend the automatic contract email to the client, and does its link expire?
The email with the contract and the upload link is always sent to contactInfo.email and cannot be disabled, because the contract is between Novus and the client. The link does not expire and always shows the current status of the request. Resending is not available: if a new email is needed, cancel the request with DELETE /api/v1/requests/{requestId} (only before approval) and create a new one, with a new Idempotency-Key.
How do I test the onboarding flow in the sandbox? Is a real contract or Provider declaration created, and are emails sent?
In the sandbox, no real contract is created and no Provider declaration is submitted. You can use real VAT numbers or any nine-digit number with a valid check digit. The flow: create a request, download the PDF, upload a signed PDF, send Novus the requestId so that they approve it, and track provisioning until COMPLETED. Also test the 409 DUPLICATE_OPEN_REQUEST and 422 errors. Emails are really sent, so only put your own addresses in contactInfo.email.
When can the new client start issuing: at provisioning.status = COMPLETED, or must I wait until the Provider declaration is accepted?
As soon as provisioning.status becomes COMPLETED (or you receive the request.provisioned webhook), the VAT number is active on your API key and you issue normally through the Provider API. You do not need to wait for aadeStatement.status to become ACCEPTED; SUBMITTED is enough. The client accepts the declaration in myAADE in parallel. If they do not, it is deemed accepted after 10 days (PRESUMED_ACCEPTED).
What should my application do when it receives the client.statement_recalled webhook?
For now, Novus recommends that you do not stop issuing automatically because of this event, since AADE is still defining the revocation process. On the Novus side, a revocation happens when the client's transaction types change significantly (e.g. B2C is added for a B2B-only client). The old declaration is then revoked and a new one is submitted, so the event alone does not mean there is a problem. Always confirm the status with GET /api/v1/requests/{requestId} and wait for instructions from Novus.
See: Webhooks
How do I disconnect an active client from my software house after APPROVED?
After approval, the request cannot be cancelled through the API (DELETE returns 409 INVALID_TRANSITION). Disconnection is only done in agreement with Novus, because it has contractual consequences. It only removes your link: it does not cancel the client's contract with Novus or revoke the Provider declaration, if the client continues through another software house. If a client comes to you from another software house, you simply send a request and get LINK_EXISTING.
The client's accountant says that Provider declarations are missing in myAADE, although the client issues through Novus. Who submits what?
For each issuer VAT number, three things are needed: a contract with Novus, the authorization of Novus as Provider by the client themselves in myAADE, and the Provider declaration to AADE (A.1112/2025). The client does their part when they start using the Provider. Novus submits the Provider declaration only after the VAT number has been activated with its own contract, from the portal or the Onboarding API, and the client accepts it in myAADE within 10 days. If a software house serves the client, the process goes through the software house.
Does the API also work for clients I activated before I started using the Onboarding API?
Every VAT number that is already active on your API key issues normally through the Provider API, however it was activated. If you send an Onboarding API request for a VAT number that is already active on your key, you get 409 CLIENT_ALREADY_LINKED. No new request is needed.
How can the client or their accountant confirm that Novus Conceptus is an AADE-licensed e-invoicing provider?
Novus Conceptus is a licensed e-invoicing provider (ΥΠΑΗΕΣ) with provider code 005. It is on the public list of licensed providers on the AADE website, where the accountant can verify it. The license details (number, licensing date and renewal date) are in the "Who we are" section of the documentation.
See: Issue tax documents from your application with a single call