Σφάλματα & statusCode

Ένα παραστατικό μπορεί να αποτύχει σε δύο διαφορετικά επίπεδα. Η εφαρμογή σας πρέπει να χειρίζεται και τα δύο.

flowchart TD
    A[POST SendInvoices] --> B{HTTP status}
    B -- "401" --> U[Άκυρο API key ή ΑΦΜ<br/>χωρίς δικαίωμα<br/>διορθώστε τις ρυθμίσεις]
    B -- "400" --> V["Απορρίφθηκε από τον Πάροχο<br/>body: { errors: [...] }<br/><b>ΔΕΝ στάλθηκε στην ΑΑΔΕ</b><br/>διορθώστε και ξαναστείλτε"]
    B -- "5xx / timeout / χωρίς σύνδεση" --> T["Ο Πάροχος δεν απαντά<br/>ξαναστείλτε με transmissionFailure = 1<br/>(μέσα σε 1 ημέρα)"]
    B -- "200" --> S{"response[0].statusCode"}
    S -- Success --> OK[Εκδόθηκε ✔]
    S -- Offline --> OFF["Εκδόθηκε ✔ — η ΑΑΔΕ δεν απαντούσε<br/>ο Πάροχος θα το διαβιβάσει<br/><b>ΜΗΝ το ξαναστείλετε</b>"]
    S -- "ValidationError<br/>XMLSyntaxError<br/>TechnicalError" --> E["Απορρίφθηκε από την ΑΑΔΕ<br/>δείτε το errors[].error[]<br/>διορθώστε και ξαναστείλτε"]

Κωδικοί HTTP

HTTP	Τι σημαίνει	Body	Εκδόθηκε;
200	Η κλήση επεξεργάστηκε. Δείτε το statusCode.	{ "response": [ … ] }	Ανάλογα με το statusCode
400	Απορρίφθηκε από τους ελέγχους του Παρόχου. Δείτε τη λίστα των κανόνων.	{ "errors": ["…"] }	Όχι
401	Λείπει ή είναι άκυρο το API-KEY, ή ο ΑΦΜ εκδότη δεν είναι ενεργός στον λογαριασμό σας.	κενό ή { "errors": ["…"] }	Όχι
404	Δεν βρέθηκε, π.χ. άγνωστο τραπέζι ή παραστατικό.	{ "errors": ["…"] }	—
5xx	Απρόσμενο σφάλμα στον Πάροχο.	διάφορο	Θεωρήστε ότι δεν εκδόθηκε, δείτε παρακάτω

statusCode

statusCode	Εκδόθηκε;	Τι κάνετε
Success		Αποθηκεύετε invoiceMark, invoiceUid, authenticationCode, invoiceUrl.
Offline		Το παραστατικό εκδόθηκε, με UID. Η ΑΑΔΕ δεν απαντούσε και ο Πάροχος θα το διαβιβάσει αυτόματα. Μην το ξαναστείλετε. Δείτε Offline.
ValidationError		Η ΑΑΔΕ απέρριψε τα δεδομένα. Διαβάστε το errors[].error[].code και το message, διορθώστε και ξαναστείλτε. Κωδικοί: Κωδικοί σφαλμάτων ΑΑΔΕ.
XMLSyntaxError		Μια τιμή είναι εκτός του σχήματος της ΑΑΔΕ, π.χ. άκυρο invoiceType ή κωδικός. Διορθώστε και ξαναστείλτε.
TechnicalError		Απρόσμενο σφάλμα στην ΑΑΔΕ. Ξαναδοκιμάστε αργότερα.

Το HTTP 200 δεν σημαίνει επιτυχία

Και ένα παραστατικό που απορρίφθηκε (ValidationError) επιστρέφει HTTP 200. Το παραστατικό έχει εκδοθεί μόνο όταν το statusCode είναι Success ή Offline.

Παράδειγμα απόρριψης από την ΑΑΔΕ:

{
  "response": [
    {
      "index": 1,
      "statusCode": "ValidationError",
      "invoiceMark": 0,
      "invoiceUid": null,
      "invoiceUrl": null,
      "credits": null,
      "errors": [
        {
          "error": [
            {
              "code": "228",
              "message": "The UID: C10262E0AE13C6AFD7DD2C980900BB0DF266D9C5 is invalid . It has already been sent for another invoice (MARK:400001939576037 , AUTHENTICATION_CODE:1D0F38488D532D3BB715408E01283D39E8D56A3A)"
            }
          ]
        }
      ]
    }
  ]
}

Σφάλμα 228: «έχει ήδη σταλεί»

Συνήθως σημαίνει ότι η προηγούμενη προσπάθειά σας πέτυχε, αλλά δεν πήρατε ποτέ την απάντηση (π.χ. timeout). Το μήνυμα περιέχει το MARK και το Authentication Code του αρχικού. Χρησιμοποιήστε αυτά αντί να το εκδώσετε ξανά. Το αρχικό το βρίσκετε και με το RequestTransmittedDocs, με φίλτρο το uid.

Offline & επαναλήψεις

• Δεν φτάνετε στον Πάροχο (timeout, σφάλμα δικτύου, 5xx): ξαναστείλτε το ίδιο παραστατικό. Αν ο Πάροχος συνεχίζει να μην απαντά, εκδώστε το παραστατικό τοπικά και στείλτε το μέσα σε 1 ημέρα με "transmissionFailure": 1.
• statusCode = "Offline": το παραστατικό εκδόθηκε, αλλά η ΑΑΔΕ δεν απαντούσε και ο Πάροχος θα το διαβιβάσει αργότερα. Μην το ξαναστείλετε ποτέ. Το τελικό MARK το βρίσκετε με RequestTransmittedDocs?uid=….

Αναλυτικά, βήμα βήμα: Offline & επαναλήψεις.

Η μορφή των σφαλμάτων με μια ματιά

Πάροχος (HTTP 400/401/404)ΑΑΔΕ (HTTP 200)

{ "errors": [ "The sum of the payment methods amount must be equal to the total gross value of the invoices." ] }

{ "response": [ { "statusCode": "ValidationError", "errors": [ { "error": [ { "code": "203", "message": "…" } ] } ] } ] }