Προέλεγχος (στη Ρουμανία: CIUS-RO), υποβολή στο εθνικό σύστημα (στη Ρουμανία: SPV), κανονικοποιημένη κατάσταση, υπογεγραμμένη απάντηση και εισερχόμενα τιμολόγια.
← Επιστροφή στην τεκμηρίωση του API
Το πρώτο τιμολόγιο σε 6 βήματα
- Εκτελέστε POST /v1/invoices/{id}/efactura/validate. Ο προέλεγχος (στη Ρουμανία: CIUS-RO) δεν στέλνει τίποτα στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης και σας λέει ακριβώς τι θα απορριπτόταν.
- Καταθέστε το με POST /v1/invoices/{id}/efactura/submit, πάντα με Idempotency-Key. Λαμβάνετε ένα submission_id και μια κατάσταση.
- Ελέγχετε περιοδικά το GET /v1/efactura/submissions/{id} μέχρι να φτάσει σε accepted ή rejected.
- Επιβάλετε νέο ερώτημα στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης με POST /v1/efactura/submissions/{id}/refresh — μετράει στον κουβά των 10 ανά λεπτό.
- Κατεβάστε το αρχείο με την υπογεγραμμένη απόκριση του εθνικού συστήματος (στη Ρουμανία: ANAF) μέσω GET /v1/efactura/submissions/{id}/download.
Όλα τα Ένδποιντς
| Μέθοδος | Endpoint | Scope | Idempotency-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
Η διαδρομή προς το εθνικό σύστημα ηλεκτρονικής τιμολόγησης
Σφάλματα
| Κατάσταση | Τύπος | Κωδικός |
|---|---|---|
| 422 | invalid_request_error | cius_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 στην υποστήριξη.