Κωδικοί καυσίμων myDATA (fuel_code): έκδοση παραστατικών πρατηρίου μέσω API

Ένα πρατήριο υγρών καυσίμων εκδίδει τα ίδια παραστατικά με κάθε άλλη επιχείρηση, με μία διαφορά: το myDATA θέλει να ξέρει ποιο καύσιμο πουλήθηκε σε κάθε γραμμή. Αυτό γίνεται με δύο πεδία, έναν διακόπτη στο header και έναν κωδικό ανά γραμμή.

{
  "fuel_invoice": true,
  "invoice_lines": [
    { "fuel_code": 20 }
  ]
}

Αυτά τα δύο είναι όλη η βάση. Τα υπόλοιπα του άρθρου είναι το πού μπαίνει το καθένα, τι δέχεται, τι απορρίπτει η ΑΑΔΕ, και δύο πλήρη payloads που μπορείς να αντιγράψεις.

Πριν τα πεδία: επιτρέπεται η λιανική μέσω παρόχου;

Η συνηθισμένη υπόθεση είναι ότι το πρατήριο είναι δεμένο με ΦΗΜ και ότι ο πάροχος αφορά μόνο χονδρική και στόλους. Δεν είναι έτσι, και η απάντηση βρίσκεται στο ίδιο το κείμενο της απόφασης.

Δύο διευκρινίσεις που αξίζουν όσο και το ίδιο το συμπέρασμα. Πρώτον, η απόφαση αυτή ρυθμίζει τη διαβίβαση. Το δικαίωμα να εκδώσεις σεσημασμένο παραστατικό λιανικής προϋποθέτει αδειοδοτημένο πάροχο ΥΠΑΗΕΣ, κάτι διαφορετικό από μια απλή σύνδεση στο myDATA. Η διάκριση αναλύεται στο άρθρο για τη σύνδεση SaaS και ERP με το myDATA.

Δεύτερον, και είναι το σημείο που μπερδεύει τους περισσότερους: το σύστημα εισροών-εκροών είναι ξεχωριστή υποχρέωση και δεν την αγγίζει τίποτα από τα παραπάνω. Ο πάροχος αναλαμβάνει τη σήμανση και τη διαβίβαση του παραστατικού. Τη μέτρηση του καυσίμου στις δεξαμενές και στις αντλίες την κάνει το σύστημα εισροών-εκροών, όπως και πριν.

Τα τέσσερα πεδία και πού ζει το καθένα

Η θέση κάθε πεδίου είναι το μισό της δουλειάς εδώ, γιατί ένα πεδίο στο λάθος επίπεδο δεν βγάζει σφάλμα. Απλώς αγνοείται.

Οι κωδικοί καυσίμων του myDATA

Είκοσι οκτώ κωδικοί καυσίμων, συν την τιμή 999 για λοιπές χρεώσεις υπηρεσιών. Στέλνονται ως ακέραιοι, όχι ως κείμενο. Ένας κωδικός εκτός λίστας απορρίπτεται από τη Wrapp κατά τη δημιουργία του draft, με HTTP 422.

Πρατήριο: απόδειξη λιανικής με δύο καύσιμα και μία υπηρεσία

Το τυπικό παραστατικό αντλίας: ΑΛΠ (τύπος 11.1), αντισυμβαλλόμενος μόνο με όνομα, περισσότερα από ένα καύσιμα στην ίδια απόδειξη, και μία γραμμή 999 για ό,τι δεν είναι καύσιμο. Αντικατέστησε το billing_book_id με το id της δικής σου σειράς, από το GET /billing_books.

{
  "invoice_type_code": "11.1",
  "billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "payment_method_type": 1,
  "fuel_invoice": true,
  "net_total_amount": 91.00,
  "vat_total_amount": 21.84,
  "total_amount": 112.84,
  "payable_total_amount": 112.84,
  "counterpart": {
    "name": "Λιανική πώληση",
    "country_code": "GR"
  },
  "invoice_lines": [
    {
      "line_number": 1,
      "name": "Αμόλυβδη 95",
      "quantity": 40,
      "unit_price": 1.40,
      "net_total_price": 56.00,
      "vat_rate": 24,
      "vat_total": 13.44,
      "subtotal": 69.44,
      "classification_category": "category1_1",
      "classification_type": "E3_561_003",
      "fuel_code": 10
    },
    {
      "line_number": 2,
      "name": "Diesel κίνησης",
      "quantity": 20,
      "unit_price": 1.50,
      "net_total_price": 30.00,
      "vat_rate": 24,
      "vat_total": 7.20,
      "subtotal": 37.20,
      "classification_category": "category1_1",
      "classification_type": "E3_561_003",
      "fuel_code": 20
    },
    {
      "line_number": 3,
      "name": "Πλύσιμο",
      "quantity": 1,
      "unit_price": 5.00,
      "net_total_price": 5.00,
      "vat_rate": 24,
      "vat_total": 1.20,
      "subtotal": 6.20,
      "classification_category": "category1_3",
      "classification_type": "E3_561_003",
      "fuel_code": 999
    }
  ]
}

Πρόσεξε τη γραμμή 999. Επιτρέπεται μία ανά παραστατικό, και η καθαρή της αξία (5,00) δεν πρέπει να ξεπερνά το άθροισμα των καθαρών αξιών των υπόλοιπων γραμμών (56,00 + 30,00). Οι κωδικοί κατάταξης και ο κωδικός τρόπου πληρωμής είναι δικές σου φορολογικές επιλογές ανά περίπτωση: οι αποδεκτές τιμές είναι στην τεκμηρίωση του API.

Οι τρεις κανόνες επικύρωσης της ΑΑΔΕ

Η ΑΑΔΕ επιβάλλει τρεις κανόνες γύρω από αυτά τα πεδία, και οι τρεις ελέγχονται κατά την έκδοση, όχι στη δημιουργία του draft.

Πετρέλαιο θέρμανσης: τέσσερα υποχρεωτικά δεδομένα

Εδώ το σχήμα γίνεται απαιτητικό, και η απαίτηση δεν είναι δική μας. Η Α.1139/2025 (ΦΕΚ Β΄ 5464/13.10.2025) πρόσθεσε παράγραφο στην Α.1138/2020 και ορίζει ότι, στην περίπτωση διαβίβασης μέσω Παρόχου Υπηρεσιών Ηλεκτρονικής Έκδοσης Στοιχείων, τα παραστατικά αγοράς πετρελαίου θέρμανσης για τη χορήγηση του επιδόματος διαβιβάζουν υποχρεωτικά τέσσερα επιπλέον δεδομένα.

Το τέταρτο είναι εκείνο που παρερμηνεύεται. Η απόφαση λέει «επιλέγεται η ένδειξη «Επίδομα Θέρμανσης» της στήλης 40 [Παρατηρήσεις - Επισημάνσεις]», και διαβάζεται κυριολεκτικά: πρόκειται για διακριτή τιμή σε κωδικοποιημένη στήλη, όχι για ελεύθερο κείμενο. Αν τη γράψεις στα notes, η υποχρέωση δεν καλύπτεται. Η απόφαση κατονομάζει τους τύπους παραστατικών 1.1, 1.4, 1.6, 5.1, 5.2, 11.1 και 11.4.

{
  "invoice_type_code": "11.1",
  "billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "payment_method_type": 1,
  "fuel_invoice": true,
  "special_invoice_category": 11,
  "net_total_amount": 800.00,
  "vat_total_amount": 192.00,
  "total_amount": 992.00,
  "payable_total_amount": 992.00,
  "counterpart": {
    "name": "Γιάννης Ιωάννου",
    "country_code": "GR",
    "vat": "123456789",
    "supply_account_no": "12345678"
  },
  "invoice_lines": [
    {
      "line_number": 1,
      "name": "Πετρέλαιο θέρμανσης",
      "quantity": 800,
      "unit_price": 1.00,
      "net_total_price": 800.00,
      "vat_rate": 24,
      "vat_total": 192.00,
      "subtotal": 992.00,
      "classification_category": "category1_1",
      "classification_type": "E3_561_003",
      "fuel_code": 30
    }
  ]
}

Για πώληση σε επιχείρηση αντί σε ιδιώτη, η δομή είναι η ίδια και αλλάζει η κατάταξη: τιμολόγιο 1.1 με classification_type E3_561_001, γιατί το τιμολόγιο είναι χονδρική. Τα τέσσερα δεδομένα της απόφασης παραμένουν, και καλύπτονται και τα πιστωτικά.

Το λάθος που δεν βγάζει σφάλμα

Ένα payload αξίζει να δεις και ανάποδα. Παρακάτω είναι το πιο συχνό λάθος του σχήματος: το supply_account_no στο ανώτερο επίπεδο, αντί μέσα στο counterpart.

{
  "fuel_invoice": true,
  "special_invoice_category": 11,
  "supply_account_no": "12345678",
  "counterpart": {
    "name": "Γιάννης Ιωάννου",
    "vat": "123456789"
  }
}

Το παραστατικό εκδίδεται κανονικά. Δεν παίρνεις σφάλμα, και ο Αριθμός Παροχής Ηλεκτρικού Ρεύματος απλώς λείπει: το API αγνοεί άγνωστα πεδία στο ανώτερο επίπεδο αντί να τα απορρίψει. Η υποχρέωση της Α.1139/2025 μένει ακάλυπτη χωρίς κανένα ορατό σημάδι. Ο μόνος τρόπος να το πιάσεις είναι να διαβάσεις πίσω το παραστατικό και να επιβεβαιώσεις ότι το πεδίο επέστρεψε.

Πώς διαβάζεις τα πεδία πίσω

Τα fuel_invoice και fuel_code επιστρέφουν από το find_invoice_by_id και από το find_all_invoices. Το supply_account_no επιστρέφει μέσα στο counterpart, εκεί ακριβώς όπου το έστειλες. Το GET /invoices/{id} είναι σκόπιμα λιτό, μια προβολή φορολογικής κατάστασης με ΜΑΡΚ, UID, QR, σειρά και αριθμό, οπότε δεν είναι το σωστό endpoint για αυτόν τον έλεγχο.

Χρήσιμο για idempotency: το external_id είναι μοναδικό ανά λογαριασμό και ένα διπλότυπο απορρίπτεται κατά τη δημιουργία του draft, οπότε μια επανάληψη κλήσης μετά από timeout δεν παράγει δεύτερο παραστατικό. Το ίδιο πεδίο δέχεται και το find_invoice_by_id στη θέση του id, οπότε μπορείς να διαβάσεις πίσω ένα παραστατικό με το δικό σου αναγνωριστικό.

Τι δείχνει το ίδιο το παραστατικό

Τα πεδία δεν μένουν στο myDATA. Στο παραστατικό που λαμβάνει ο πελάτης τυπώνονται η ένδειξη «(Παραστατικό Καυσίμων)» δίπλα στον τίτλο, ο κωδικός με την περιγραφή του σε κάθε γραμμή, για παράδειγμα «(30 - Diesel Heat)», η «Ειδική Κατηγορία Παραστατικού: Επίδομα Θέρμανσης» και ο «Αρ. Παροχής Ηλ. Ρεύματος».

Πώς ξεκινάς

Για πρόσβαση στο staging περιβάλλον, συμπλήρωσε τη φόρμα στη σελίδα συνεργασίας μέσω API με το ΑΦΜ σου. Ο staging λογαριασμός σου δημιουργείται αυτόματα και θα επανέλθουμε άμεσα με τα credentials σου, ώστε να δοκιμάσεις κάθε τύπο παραστατικού πριν βγει σε παραγωγή. Το πλήρες σχήμα των πεδίων είναι στην τεκμηρίωση του REST API.

Αν το ερώτημα πίσω από όλα αυτά είναι ευρύτερο, δηλαδή τι αλλάζει συνολικά στην έκδοση παραστατικών από την 1η Οκτωβρίου 2026, το χρονοδιάγραμμα και οι υποχρεώσεις είναι εκεί.

Συχνές ερωτήσεις

Χρειάζεσαι βοήθεια;

Αν έχεις απορία για αυτό το θέμα ή θέλεις να σιγουρευτείς ότι όλα ρυθμίστηκαν σωστά, επικοινώνησε μαζί μας και θα το δούμε μαζί.