Μετάβαση στο περιεχόμενο

Περιβάλλοντα & API key

Υπάρχουν δύο εντελώς ανεξάρτητα περιβάλλοντα, το καθένα με δικό του portal, δικό του λογαριασμό και δικό του API key.

Sandbox Production
Σκοπός Ανάπτυξη και δοκιμές Πραγματικά παραστατικά με φορολογική ισχύ
Base URL https://provider-dev.timologisi.online https://provider.timologisi.online
Portal developer.portal.timologisi.online portal.timologisi.online
Swagger provider-dev.timologisi.online/index.html provider.timologisi.online/index.html
Λογαριασμός Αυτόματα, με εγγραφή Μετά την πιστοποίηση
ΑΦΜ εκδότη Ο ΑΦΜ που δηλώσατε στην εγγραφή ενεργοποιείται αυτόματα Κάθε ΑΦΜ πελάτη ενεργοποιείται μετά από σύμβαση και εξουσιοδότηση (Onboarding API)
Credits Δοκιμαστικά Αγορά από το portal
Διατήρηση δεδομένων Τα παραστατικά διαγράφονται μετά από 30 ημέρες Μόνιμη αρχειοθέτηση

1. Δημιουργία λογαριασμού (Sandbox)

  1. Ανοίξτε τη φόρμα εγγραφής.
  2. Δηλώστε email και ΑΦΜ.
  3. Επιβεβαιώστε τον λογαριασμό από το email που θα λάβετε και ορίστε κωδικό.
  4. Συνδεθείτε στο portal. Εκεί βρίσκετε το API key σας.

Από το portal μπορείτε επίσης να:

  • δείτε και να αναζητήσετε τα παραστατικά που εκδόσατε,
  • δείτε τους εξουσιοδοτημένους ΑΦΜ,
  • ανεβάσετε λογότυπα πελατών. Το logoId που παίρνετε μπαίνει στο πεδίο additionalDetails.logoId.
  • (Production) αγοράσετε credits και ζητήσετε ενεργοποίηση νέου ΑΦΜ.

2. Αυθεντικοποίηση

Κάθε κλήση στέλνει το κλειδί στο HTTP header API-KEY:

POST /api/v1/Provider/SendInvoices HTTP/1.1
Host: provider-dev.timologisi.online
API-KEY: <το κλειδί σας>
Content-Type: application/json
Αποτέλεσμα Σημαίνει
401 Unauthorized χωρίς σώμα Το header λείπει, το κλειδί είναι λάθος ή ανενεργό, ή χρησιμοποιείτε κλειδί Sandbox σε Production (ή ανάποδα).
401 με {"errors": ["You don't have the authority to send for this vat numbers ..."]} Το κλειδί είναι σωστό, αλλά ο ΑΦΜ του εκδότη δεν είναι ενεργοποιημένος στον λογαριασμό σας.

Κρατήστε το κλειδί μυστικό

Το API key εκδίδει παραστατικά με φορολογική ισχύ και χρεώνει τα credits σας.

  • Μην το βάζετε σε κώδικα που τρέχει σε browser ή σε δημόσιο repository.
  • Αποθηκεύστε το κρυπτογραφημένο, όπως και τα υπόλοιπα credentials της εφαρμογής σας.
  • Αν διαρρεύσει, επικοινωνήστε αμέσως μαζί μας για να ακυρωθεί και να εκδοθεί νέο.

3. Ένα κλειδί, πολλοί πελάτες

Ως software house χρησιμοποιείτε ένα API key για όλους τους πελάτες σας. Κάθε παραστατικό λέει για ποιον πελάτη εκδίδεται μέσω του issuer.vatNumber. Ο Πάροχος ελέγχει ότι ο ΑΦΜ αυτός είναι ενεργοποιημένος στον λογαριασμό σας. Τα credits είναι κοινά για όλους τους ΑΦΜ του λογαριασμού.

4. Τεχνικές απαιτήσεις

  • HTTPS / TLS 1.2+.
  • JSON σε UTF-8. Τα ονόματα πεδίων δεν κάνουν διάκριση κεφαλαίων-πεζών, αλλά προτείνουμε camelCase όπως στα παραδείγματα.
  • Ημερομηνίες σε μορφή yyyy-MM-dd και ώρες σε μορφή HH:mm:ss.
  • Δεκαδικά ως JSON numbers με τελεία (124.25) και έως 2 δεκαδικά για ποσά.
  • Ειδικοί χαρακτήρες μέσα σε strings: escape κατά JSON (\", \\, \n, \r, \t, \b, \f).
  • Timeout: προτείνουμε τουλάχιστον 60″ για το SendInvoices, γιατί η κλήση περιμένει την απάντηση της ΑΑΔΕ και τη δημιουργία του PDF.