Εθνικό σύστημα ηλεκτρονικής τιμολόγησης μέσω του API

Προέλεγχος (στη Ρουμανία: CIUS-RO), υποβολή στο εθνικό σύστημα (στη Ρουμανία: SPV), κανονικοποιημένη κατάσταση, υπογεγραμμένη απάντηση και εισερχόμενα τιμολόγια.

Προέλεγχος (στη Ρουμανία: CIUS-RO), υποβολή στο εθνικό σύστημα (στη Ρουμανία: SPV), κανονικοποιημένη κατάσταση, υπογεγραμμένη απάντηση και εισερχόμενα τιμολόγια.

← Επιστροφή στην τεκμηρίωση του API

Το πρώτο τιμολόγιο σε 6 βήματα

  1. Εκτελέστε POST /v1/invoices/{id}/efactura/validate. Ο προέλεγχος (στη Ρουμανία: CIUS-RO) δεν στέλνει τίποτα στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης και σας λέει ακριβώς τι θα απορριπτόταν.
  2. Καταθέστε το με POST /v1/invoices/{id}/efactura/submit, πάντα με Idempotency-Key. Λαμβάνετε ένα submission_id και μια κατάσταση.
  3. Ελέγχετε περιοδικά το GET /v1/efactura/submissions/{id} μέχρι να φτάσει σε accepted ή rejected.
  4. Επιβάλετε νέο ερώτημα στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης με POST /v1/efactura/submissions/{id}/refresh — μετράει στον κουβά των 10 ανά λεπτό.
  5. Κατεβάστε το αρχείο με την υπογεγραμμένη απόκριση του εθνικού συστήματος (στη Ρουμανία: ANAF) μέσω GET /v1/efactura/submissions/{id}/download.

Όλα τα Ένδποιντς

ΜέθοδοςEndpointScopeIdempotency-KeyΑιτήματα / λεπτό
GET/invoices/{invoice_id}/xml
Λήψη του XML UBL (στη Ρουμανία: CIUS-RO)
invoices:read—120
POST/invoices/{invoice_id}/efactura/validate
Προέλεγχος (στη Ρουμανία: CIUS-RO) — επικύρωση χωρίς αποστολή
efactura:read—120
POST/invoices/{invoice_id}/efactura/submit
Υποβολή του τιμολογίου στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης (στη Ρουμανία: ANAF/SPV)
efactura:submitυποχρεωτικό10
GET/efactura/submissions
Λίστα υποβολών προς το εθνικό σύστημα ηλεκτρονικής τιμολόγησης
efactura:read—120
GET/efactura/submissions/{submission_id}
Ανάκτηση μίας υποβολής
efactura:read—120
POST/efactura/submissions/{submission_id}/refresh
Αίτημα προς το εθνικό σύστημα ηλεκτρονικής τιμολόγησης για την τρέχουσα κατάσταση
efactura:read—10
GET/efactura/submissions/{submission_id}/download
Λήψη του αρχείου της υπογεγραμμένης απάντησης
efactura:read—120
GET/efactura/inbox
Τιμολόγια προμηθευτών που ελήφθησαν μέσω του εθνικού συστήματος ηλεκτρονικής τιμολόγησης
efactura:read—120
GET/efactura/inbox/{inbound_id}
Ανάκτηση ενός εισερχόμενου τιμολογίου
efactura:read—120
GET/efactura/inbox/{inbound_id}/download
Λήψη του αρχείου εισερχόμενου τιμολογίου
efactura:read—120
POST/efactura/inbox/sync
Λήψη νέων μηνυμάτων του εθνικού συστήματος ηλεκτρονικής τιμολόγησης στα εισερχόμενα
efactura:read—10

Τι είναι το API 4invoices

bash
# CIUS-RO preflight. Sends NOTHING to ANAF.
curl -sS -X POST "https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate?include_xml=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"invoice_id":"inv_01J7ABC","valid":false,
#    "errors":["buyer.county is required for RO buyers"],
#    "xml_base64":"PD94bWwg..."}
bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/submit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: efactura-inv_01J7ABC-1'

# → {"submission_id":"sub_01J7XYZ","status":"queued"}
python
import time, requests

BASE = "https://api.4invoices.net/v1"
TERMINAL = {"accepted", "rejected"}
H = {"Authorization": f"Bearer {token}"}

def wait_for_anaf(submission_id, timeout=900):
    deadline = time.time() + timeout
    delay = 15
    while time.time() < deadline:
        r = requests.get(f"{BASE}/efactura/submissions/{submission_id}", headers=H, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]
        if status in TERMINAL:
            return r.json()
        # /refresh asks ANAF directly and shares the 10/min submit bucket.
        requests.post(f"{BASE}/efactura/submissions/{submission_id}/refresh", headers=H, timeout=30)
        time.sleep(delay)
        delay = min(delay * 2, 120)
    raise TimeoutError(submission_id)
bash
# Pull new SPV messages, then read the inbound supplier invoices.
curl -sS -X POST https://api.4invoices.net/v1/efactura/inbox/sync \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS "https://api.4invoices.net/v1/efactura/inbox?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# ANAF allows roughly ONE message-list call per minute per CIF,
# οπότε το /inbox/sync μετράει στο όριο αποστολής των 10/λεπτό. Προγραμματίστε το με cron, μην κάνετε Πόλινγκ.

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Η διαδρομή προς το εθνικό σύστημα ηλεκτρονικής τιμολόγησης

not_sentvalidatingqueuedsentprocessingacceptedrejectederror

Σφάλματα

ΚατάστασηΤύποςΚωδικός
422invalid_request_errorcius_ro_incomplete

Συχνά λάθη

  • Κανονικοποιημένος κύκλος ζωής: not_sent → επικύρωση → σε ουρά → στάλθηκε → επεξεργασία → accepted | rejected | σφάλμα.
  • Το accepted σημαίνει νόμιμα διαβιβασμένο. Το rejected σημαίνει ότι το εθνικό σύστημα ηλεκτρονικής τιμολόγησης το απέρριψε: διορθώστε και υποβάλετε ξανά. Το error είναι αποτυχία μεταφοράς από τη δική μας πλευρά και η επανάληψη είναι ασφαλής.
  • Η υποβολή είναι μη αναστρέψιμη: ένα δεύτερο αντίγραφο του ίδιου τιμολογίου δεν μπορεί να αποσυρθεί από το εθνικό σύστημα ηλεκτρονικής τιμολόγησης. Γι’ αυτό το Idempotency-Key είναι υποχρεωτικό.
  • Το GET /v1/invoices/{id}/xml σας δίνει το XML σε UBL (στη Ρουμανία: CIUS-RO) χωρίς καμία υποβολή — για το δικό σας αρχείο ή για έλεγχο.
  • Εισερχόμενα: το POST /v1/efactura/inbox/sync φέρνει τα νέα μηνύματα, το GET /v1/efactura/inbox τα απαριθμεί και το /download ανακτά το αρχείο κάθε εισερχόμενου τιμολογίου.
  • Τα Ένδποιντς του e-Factura λειτουργούν μόνο για Ρουμάνους Τενάντς· διαφορετικά λαμβάνετε 404.

Ερωτήσεις και απαντήσεις για προγραμματιστές

Πόσο χρόνο χρειάζεται το εθνικό σύστημα ηλεκτρονικής τιμολόγησης για να αποδεχτεί ένα τιμολόγιο;

Διαφέρει, από δευτερόλεπτα έως ώρες. Μην μπλοκάρετε την πώληση: υποβάλετε ασύγχρονα και χειριστείτε τα accepted και rejected ως γεγονότα.

Μπορώ να πάρω το XML (στη Ρουμανία: CIUS-RO) χωρίς να στείλω τίποτα στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης;

Ναι. Το GET /v1/invoices/{id}/xml παράγει το παραστατικό χωρίς υποβολή, και το /efactura/validate με include_xml=true το επιστρέφει κωδικοποιημένο σε base64.

Πόσο συχνά μπορώ να εκτελώ το inbox/sync;

Το πολύ 10 κλήσεις το λεπτό, αλλά στην πράξη στη Ρουμανία η ANAF επιτρέπει περίπου μία κλήση λίστας μηνυμάτων ανά λεπτό ανά CIF. Εκτελέστε το από cron, κάθε λίγα λεπτά.

Τι κάνω αν η κατάσταση παραμένει σφάλμα;

Το σφάλμα είναι αποτυχία μεταφοράς ή αυθεντικοποίησης από τη δική μας πλευρά, οπότε η επανάληψη είναι ασφαλής. Αν επιμένει, στείλτε το request_id στην υποστήριξη.