Το πρώτο σας παραστατικό

Θα εκδώσουμε στο Sandbox μια Απόδειξη Λιανικής Πώλησης (11.1) με μία γραμμή: 1 × καφές 10,00 € + ΦΠΑ 24%, πληρωμή με μετρητά.

Πριν ξεκινήσετε

• Έχετε API key για το Sandbox.
• Αντικαταστήστε το 123456789 με τον ΑΦΜ που δηλώσατε στην εγγραφή σας.
• Βάλτε στο issueDate τη σημερινή ημερομηνία. Η ΑΑΔΕ δεν δέχεται από Πάροχο παραστατικό με άλλη ημερομηνία (σφάλμα 238).
• Κάθε φορά που το ξαναστέλνετε, αλλάξτε το aa. Ίδια σειρά + ΑΑ σημαίνει ίδιο UID, και απορρίπτεται ως διπλότυπο.

1. Το 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": "τεμ.",
          "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": "Ελλάδα"
        },
        "additionalDetails": {
          "documentLabel": "Απόδειξη Λιανικής Πώλησης",
          "paymentMethodInvoiceLabel": "Μετρητά",
          "documentSizeCode": 1
        }
      }
    }
  ]
}

Τι σημαίνει κάθε μπλοκ:

Μπλοκ	Ρόλος
issuer	Ο εκδότης. Ο ΑΦΜ πρέπει να είναι ενεργοποιημένος στον λογαριασμό σας. Η branch είναι η εγκατάσταση στο Taxis (έδρα = 0).
invoiceHeader	Σειρά, ΑΑ, ημερομηνία και τύπος παραστατικού.
paymentMethods	Τρόποι πληρωμής. Το άθροισμα πρέπει να ισούται με το totalGrossValue.
invoiceDetails	Οι γραμμές, με κατηγορία ΦΠΑ και χαρακτηρισμό εσόδων.
invoiceSummary	Τα σύνολα. Πρέπει να συμφωνούν με το άθροισμα των γραμμών.
providerAdditionalInvoiceDetails	Στοιχεία μόνο για το PDF (επωνυμία, διεύθυνση, ετικέτες). Δεν πηγαίνουν στην ΑΑΔΕ.

2. Στείλτε το

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. Η απάντηση

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
    }
  ]
}

Αποθηκεύστε στη βάση σας τα invoiceMark, invoiceUid, authenticationCode και invoiceUrl. Θα σας χρειαστούν για συσχετίσεις (π.χ. πιστωτικά), αναζητήσεις και επανεκτύπωση.

Έτοιμο

Ανοίξτε το invoiceUrl για να δείτε το PDF. Αν πήρατε statusCode διαφορετικό από Success, δείτε το Errors & status codes. Το μήνυμα στο errors[].error[].message λέει ακριβώς τι να διορθώσετε.

Επόμενα βήματα

• Όλα τα πεδία του παραστατικού: SendInvoices reference.
• Όλα τα είδη παραστατικών με έτοιμο JSON: Τιμολόγια & αποδείξεις.
• Κάρτα/IRIS, εστίαση, διακίνηση, B2G: δείτε τους αντίστοιχους οδηγούς στο μενού αριστερά.