Βασικό URL
https://freebillgen.com/api/v1Έλεγχος ταυτότητας
Κάθε αίτημα χρησιμοποιεί ένα Bearer token. Δημιουργήστε ένα στις Ρυθμίσεις → Κλειδιά API, δώστε του τα δικαιώματα ανάγνωσης ή εγγραφής ανά πόρο που χρειάζεται, ορίστε προαιρετικά ημερομηνία λήξης και στείλτε το σε κάθε αίτημα:
Authorization: Bearer <your-api-key>Τα αιτήματα συνδέονται με τον λογαριασμό που δημιούργησε το κλειδί και ελέγχονται με βάση τα δικαιώματά του. Κρατήστε μυστικό το token και ανακαλέστε το αν εκτεθεί ή δεν χρειάζεται πλέον.
Τι μπορείτε να κάνετε
- Ανάγνωση τιμολογίων, πελατών, εταιρειών, πληρωμών και επαναλαμβανόμενων προγραμμάτων
- Δημιουργία και ενημέρωσή τους (API εγγραφής - Pro)
- Λήψη αναφορών ΦΠΑ και παλαιότητας οφειλών σε μορφή JSON
- Ανάγνωση της ίδιας περιορισμένης ουράς «Επόμενες ενέργειες» που χρησιμοποιεί ο πίνακας ελέγχου
- Ανάγνωση αρχείων ηλεκτρονικών τιμολογίων προμηθευτών που μεταφορτώσατε χειροκίνητα στα Εισερχόμενα (δεν αποτελεί σημείο παραλαβής μέσω Peppol ή email)
- Λήψη γενικών αντιστοιχίσεων OASIS UBL και UN/CEFACT CII για έλεγχο (χωρίς επικύρωση βάσει προφίλ)
- Καταχώριση τελικών σημείων webhook για συμβάντα τιμολογίων και πληρωμών (Pro)
- Idempotency-Key στις υποστηριζόμενες εγγραφές - αν αλλάξουν τα δεδομένα αιτήματος με το ίδιο κλειδί, επιστρέφεται 409
- Σελιδοποίηση με δείκτη μέσω links.next, ρυθμιζόμενη με per_page (έως 100)
- Οι πράκτορες AI μπορούν να διαβάζουν κάθε κοινόχρηστο τιμολόγιο - schema.org/Invoice JSON-LD και Accept: application/json ή text/markdown σε κάθε υπογεγραμμένο σύνδεσμο κοινοποίησης
- Διακομιστής MCP χωρίς έλεγχο ταυτότητας και μόνο για ανάγνωση στη διεύθυνση https://freebillgen.com/api/mcp (get_invoice, verify_invoice), για πράκτορες AI
Συμβάσεις
- Idempotency
- Στις υποστηριζόμενες κλήσεις δημιουργίας ή ενέργειας, στείλτε ένα μοναδικό Idempotency-Key. Αν επαναλάβετε τα ίδια δεδομένα, λαμβάνετε ξανά την αρχική επιτυχή απάντηση. Αν αλλάξουν τα δεδομένα με το ίδιο κλειδί, επιστρέφεται 409.
- Σελιδοποίηση
- Οι λίστες αποθηκευμένων πόρων χρησιμοποιούν σελιδοποίηση με cursor. Ακολουθήστε το links.next (ή δώστε ?cursor=...) και ρυθμίστε το ?per_page= (έως 100). Η περιορισμένη ροή ενεργειών δηλώνει το όριο και αν τα αποτελέσματα περικόπηκαν.
- Χρήματα
- Τα χρηματικά ποσά είναι ακριβείς συμβολοσειρές JSON με την ανάλυση του νομίσματος κατά ISO 4217, όπως "121.00" για EUR ή "500" για JPY. Οι τιμές μονάδας μπορούν να διατηρούν πρόσθετη ακρίβεια εισόδου.
- Αναγνωριστικά
- Κάθε πόρος προσδιορίζεται με ένα αδιαφανές id, ποτέ με διαδοχικό αριθμό.
Παράδειγμα: λίστα των τιμολογίων σας
curl https://freebillgen.com/api/v1/invoices \
-H "Authorization: Bearer $FREEBILLGEN_API_KEY"Ανοίξτε την πλήρη διαδραστική αναφορά API →
Ερωτήσεις API τιμολογίων
Είναι δωρεάν το API τιμολογίων;
Ναι. Το API ανάγνωσης περιλαμβάνεται δωρεάν. Το API εγγραφής και τα εξερχόμενα webhook περιλαμβάνονται στο Lifetime Pro των 49 € με τον φόρο στην τιμή: μία πληρωμή, χωρίς μηνιαία χρέωση ή ετήσια ανανέωση.
Πώς κάνω έλεγχο ταυτότητας;
Δημιουργήστε ένα Bearer token στο Ρυθμίσεις -> Κλειδιά API, εκχωρήστε του δικαιώματα ανάγνωσης/εγγραφής ανά πόρο και στείλτε το ως κεφαλίδα Authorization: Bearer σε κάθε αίτημα. Τα κλειδιά περιορίζονται στον δικό σας λογαριασμό και μπορούν να ανακληθούν ή να λήξουν.
Μπορώ να δημιουργώ τιμολόγια προγραμματιστικά;
Ναι, μέσω του API εγγραφής, το οποίο περιλαμβάνεται στο πρόσθετο Pro. Παράγει τα ίδια επαγγελματικά τιμολόγια με την εφαρμογή ιστού, με διαδοχική αρίθμηση και ρυθμιζόμενο χειρισμό ΦΠΑ από τον διακομιστή. Το API δεν πιστοποιεί τη συμμόρφωση με την τοπική νομοθεσία.
Πώς αποφεύγω τη δημιουργία διπλότυπων τιμολογίων σε επανάληψη;
Στείλτε ένα μοναδικό Idempotency-Key στην κλήση δημιουργίας. Αν επαναλάβετε τα ίδια δεδομένα με αυτό το κλειδί, λαμβάνετε το αρχικό αποτέλεσμα. Αν το χρησιμοποιήσετε ξανά με αλλαγμένα δεδομένα, επιστρέφεται 409 αντί να επαναληφθεί σιωπηρά ένα διαφορετικό τιμολόγιο.
Μπορώ να διαβάσω τα τιμολόγια που έχω λάβει;
Ναι, δωρεάν. Το GET /api/v1/inbox εμφανίζει τα υποστηριζόμενα αρχεία προμηθευτών UBL/CII που μεταφορτώσατε χειροκίνητα και τα οποία το FreeBillGen ανέλυσε, ενώ διατηρεί το πρωτότυπο για έλεγχο. Το GET /api/v1/inbox/{id} επιστρέφει ένα αρχείο. Η αναγνώριση σύνταξης δεν αποτελεί επικύρωση προφίλ. Αυτά τα σημεία δεν μετατρέπουν το FreeBillGen σε σημείο παραλαβής Peppol, κυβερνητικού δικτύου ή email.
Μπορεί ένας πράκτορας AI να διαβάσει ένα τιμολόγιο χωρίς λογαριασμό;
Ναι. Κάθε τιμολόγιο που κοινοποιείτε με υπογεγραμμένο δημόσιο σύνδεσμο είναι αναγνώσιμο από πράκτορες στο ίδιο URL. Η σελίδα ενσωματώνει schema.org/Invoice JSON-LD. Η κεφαλίδα Accept: application/json επιστρέφει δομημένα δεδομένα (μέρη, γραμμές, σύνολα, οφειλόμενο υπόλοιπο και επιλογές πληρωμής), ενώ η Accept: text/markdown επιστρέφει μια καθαρή και οικονομική σε token απόδοση. Υπάρχει επίσης διακομιστής Model Context Protocol (MCP) χωρίς έλεγχο ταυτότητας και μόνο για ανάγνωση στο https://freebillgen.com/api/mcp, με τα εργαλεία get_invoice και verify_invoice. Η υπογραφή του συνδέσμου είναι το token πρόσβασης. Αντιμετωπίστε ολόκληρο το URL ως μυστικό, γιατί όποιος το λάβει μπορεί να ανοίξει το τιμολόγιο.