Έκδοση τιμολογίων μέσω του API

POST /invoices με Idempotency-Key, ΦΠΑ σε ποσοστά, μαζί με λίστα, πιστωτικό και σήμανση εξόφλησης.

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

Στείλτε POST /v1/invoices με αντικείμενο αγοραστής και τουλάχιστον μία εγγραφή στο γραμμές.
Προσθέστε την κεφαλίδα Idempotency-Key — είναι υποχρεωτική, ένα κλειδί ανά λογική λειτουργία.
Στείλτε το vat_rate ως ποσοστό (21) και το unit_price ως ΚΑΘΑΡΗ τιμή μονάδας.
Η απόκριση 201 περιέχει id, αριθμός, σειρά, τα σύνολα net/vat/gross και τα μεταδεδομένα που στείλατε.
Ανακτήστε το παραστατικό με GET /v1/invoices/{id}/pdf ή το XML σε UBL με GET /v1/invoices/{id}/xml.

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

Μέθοδος	Endpoint	Scope	Idempotency-Key	Αιτήματα / λεπτό
POST	/invoices Έκδοση τιμολογίου ή προτιμολόγιο	invoices:write	υποχρεωτικό	30
GET	/invoices Λίστα τιμολογίων (σελιδοποίηση με δρομέας)	invoices:read	—	120
POST	/invoices/preview-totals Υπολογισμός συνόλων χωρίς δημιουργία τίποτα	invoices:read	—	120
GET	/invoices/{invoice_id} Ανάκτηση ενός τιμολογίου	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Λήψη του PDF του τιμολογίου	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Έκδοση πιστωτικού σημειώματος που ακυρώνει αυτό το τιμολόγιο	invoices:write	υποχρεωτικό	30
POST	/invoices/{invoice_id}/payments Σήμανση τιμολογίου ως εξοφλημένου	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Σήμανση τιμολογίου ως μη εξοφλημένου	invoices:write	—	30

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

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Σελιδοποίηση με cursor: ακολουθήστε το next_cursor μέχρι το has_more να γίνει false.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

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

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# Το πιστωτικό σημείωμα παίρνει ΔΙΚΟ ΤΟΥ φορολογικό αριθμό· ο αριθμός του πρωτοτύπου δεν επαναχρησιμοποιείται ποτέ.

bash
# Σήμανση ως εξοφλημένου
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Αναίρεση
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

Σφάλματα

Κατάσταση	Τύπος	Κωδικός
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Συχνά λάθη

Οι λίστες βασίζονται σε cursor: ακολουθήστε το next_cursor μέχρι το has_more να γίνει false. Τα φίλτρα περιλαμβάνουν κατάσταση, document_kind, buyer_tax_id, issued_from, issued_to και q.
Ένα πιστωτικό ακυρωτικό είναι POST /v1/invoices/{id}/storno και λαμβάνει δικό του φορολογικό αριθμό — ο αρχικός αριθμός δεν επαναχρησιμοποιείται ποτέ.
Ένα προτιμολόγιο (document_kind proforma) δεν καταναλώνει φορολογικό αριθμό και δεν μπορεί να κατατεθεί στο εθνικό σύστημα ηλεκτρονικής τιμολόγησης.
Το μεταδεδομένα επιστρέφεται αυτούσιο στις αναγνώσεις: βάλτε εκεί το id της παραγγελίας σας και δεν χρειάζεστε πλέον ξεχωριστό πίνακα αντιστοίχισης.
Το POST /v1/invoices/preview-totals εκτελεί τους ίδιους υπολογισμούς χωρίς παρενέργειες — βολικό για να δείχνετε τα σύνολα στο δικό σας καλάθι.

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

Πόσες γραμμές μπορεί να έχει ένα τιμολόγιο;

Από 1 έως 400. Το περιγραφή περιορίζεται στους 1024 χαρακτήρες και το ποσότητα πρέπει να είναι αυστηρά θετικό.

Τι συμβαίνει αν ξαναστείλω το ίδιο αίτημα μετά από Τάιμαουτ;

Με το ίδιο Idempotency-Key λαμβάνετε το αρχικό τιμολόγιο μαζί με την κεφαλίδα Idempotency-Replayed: true. Δεν εκδίδεται δεύτερο παραστατικό.

Πώς σημειώνω ένα τιμολόγιο ως εξοφλημένο;

Το POST /v1/invoices/{id}/payments το σημειώνει ως εξοφλημένο και το DELETE στην ίδια διαδρομή το αναιρεί. Και τα δύο απαιτούν το πεδίο invoices:write.

Δείτε επίσης