Your first document

We will issue a retail receipt (11.1) in the sandbox with one line: 1 × coffee at €10.00 + 24% VAT, paid in cash.

Before you start

• You have an API key for the sandbox.
• Replace 123456789 with the VAT number (ΑΦΜ) you entered when you signed up.
• Set issueDate to today's date. AADE does not accept a document from a provider with any other date (error 238).
• Each time you send it again, change aa. The same series + number means the same UID, and it is rejected as a duplicate.

1. The request

retail-receipt-11.1.json

{
  "invoice": [
    {
      "issuer": { "vatNumber": "123456789", "country": "GR", "branch": 0 },
      "invoiceHeader": {
        "series": "A",
        "aa": "1001",
        "issueDate": "2026-09-24",
        "invoiceType": "11.1",
        "currency": "EUR"
      },
      "paymentMethods": [
        { "type": 3, "amount": 12.40 }
      ],
      "invoiceDetails": [
        {
          "lineNumber": 1,
          "lineCode": "ESP-01",
          "lineDescription": "Espresso",
          "quantity": 1,
          "measurementUnit": 1,
          "measurementUnitLabel": "piece",
          "lineUnitPrice": 10.00,
          "totalNetPriceBeforeDiscount": 10.00,
          "totalDiscountValue": 0,
          "netValue": 10.00,
          "vatCategory": 1,
          "vatCategoryPercent": 24.00,
          "vatAmount": 2.40,
          "incomeClassification": [
            { "classificationType": "E3_561_003", "classificationCategory": "category1_1", "amount": 10.00 }
          ]
        }
      ],
      "invoiceSummary": {
        "totalNetValue": 10.00,
        "totalVatAmount": 2.40,
        "totalWithheldAmount": 0,
        "totalFeesAmount": 0,
        "totalStampDutyAmount": 0,
        "totalOtherTaxesAmount": 0,
        "totalDeductionsAmount": 0,
        "totalGrossValue": 12.40,
        "incomeClassification": [
          { "classificationType": "E3_561_003", "classificationCategory": "category1_1", "amount": 10.00 }
        ]
      },
      "providerAdditionalInvoiceDetails": {
        "issuer": {
          "name": "TEST ISSUER ΙΚΕ",
          "profession": "Καφετέρια",
          "taxoffice": "Α' Αθηνών",
          "addressStreet": "Οδός Δοκιμής",
          "addressNumber": "1",
          "addressPostalCode": "10431",
          "addressCity": "Αθήνα",
          "addressCountry": "Ελλάδα"
        },
        "counterpart": {
          "name": "Retail Client"
        },
        "additionalDetails": {
          "documentLabel": "Απόδειξη Λιανικής Πώλησης",
          "paymentMethodInvoiceLabel": "Μετρητά",
          "documentSizeCode": 0
        }
      }
    }
  ]
}

What each block means:

Block	Role
issuer	The issuer. The VAT number must be activated on your account. branch is the branch registered in Taxis (head office = 0).
invoiceHeader	Series, number, date and document type.
paymentMethods	Payment methods. The sum must equal totalGrossValue.
invoiceDetails	The lines, with VAT category and income classification.
invoiceSummary	The totals. They must match the sum of the lines.
providerAdditionalInvoiceDetails	Details for the PDF only (company name, address, labels). They are not sent to AADE.

2. Send it

cURLC# (.NET)DelphiPython

curl -X POST "https://provider-dev.timologisi.online/api/v1/Provider/SendInvoices" \
  -H "API-KEY: $NOVUS_API_KEY" \
  -H "Content-Type: application/json" \
  --data @retail-receipt-11.1.json

using var http = new HttpClient { BaseAddress = new Uri("https://provider-dev.timologisi.online"), Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Add("API-KEY", Environment.GetEnvironmentVariable("NOVUS_API_KEY"));

var json = await File.ReadAllTextAsync("retail-receipt-11.1.json");
var res = await http.PostAsync("/api/v1/Provider/SendInvoices",
    new StringContent(json, System.Text.Encoding.UTF8, "application/json"));

var body = await res.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)res.StatusCode}: {body}");

uses System.Net.HttpClient, System.Classes, System.SysUtils, System.IOUtils;

var
  Http: THTTPClient;
  Body: TStringStream;
  Resp: IHTTPResponse;
begin
  Http := THTTPClient.Create;
  Body := TStringStream.Create(TFile.ReadAllText('retail-receipt-11.1.json', TEncoding.UTF8), TEncoding.UTF8);
  try
    Http.ResponseTimeout := 60000;
    Http.CustomHeaders['API-KEY'] := GetEnvironmentVariable('NOVUS_API_KEY');
    Http.ContentType := 'application/json';
    Resp := Http.Post('https://provider-dev.timologisi.online/api/v1/Provider/SendInvoices', Body);
    Writeln(Resp.StatusCode, ': ', Resp.ContentAsString(TEncoding.UTF8));
  finally
    Body.Free;
    Http.Free;
  end;
end;

import json, os, requests

with open("retail-receipt-11.1.json", encoding="utf-8") as f:
    payload = json.load(f)

r = requests.post(
    "https://provider-dev.timologisi.online/api/v1/Provider/SendInvoices",
    headers={"API-KEY": os.environ["NOVUS_API_KEY"]},
    json=payload,
    timeout=60,
)
print(r.status_code, r.json())

3. The response

HTTP 200 OK

{
  "response": [
    {
      "index": 1,
      "statusCode": "Success",
      "invoiceUid": "C10262E0AE13C6AFD7DD2C980900BB0DF266D9C5",
      "invoiceMark": 400001939576037,
      "authenticationCode": "1D0F38488D532D3BB715408E01283D39E8D56A3A",
      "invoiceUrl": "https://provider-dev.timologisi.online/api/v1/Provider/GetInvoicePdf/671899191d6d0b3d947bc4bb.pdf",
      "qrUrl": "https://provider-dev.timologisi.online/api/v1/Provider/GetInvoicePdf/671899191d6d0b3d947bc4bb.pdf",
      "aadeQrUrl": "<ο σύνδεσμος επαλήθευσης της ΑΑΔΕ>",
      "credits": "0,50",
      "errors": null,
      "providerSignature": null
    }
  ]
}

Store invoiceMark, invoiceUid, authenticationCode and invoiceUrl in your database. You will need them for correlations (e.g. credit notes), searches and reprints.

Done

Open invoiceUrl to see the PDF. If you got a statusCode other than Success, see Errors & status codes. The message in errors[].error[].message tells you exactly what to fix.

Next steps

• All document fields: SendInvoices reference.
• Every document type with a ready-made JSON: Invoices & receipts.
• Card/IRIS, food service, goods movement, B2G: see the matching guides in the menu on the left.