Postman & παραδείγματα

Όλα όσα χρειάζεται ένας developer για να ξεκινήσει: ένα YAML (OpenAPI) και μία συλλογή Postman για κάθε API.

Τα αρχεία

API	OpenAPI (YAML)	Postman
Provider API: έκδοση παραστατικών	novus-provider-api.openapi.yaml	Novus_Provider_API.postman_collection.json
Onboarding API: ενεργοποίηση πελατών	novus-onboarding-api.openapi.yaml	Novus_Onboarding_API.postman_collection.json

• Το YAML (OpenAPI 3.1) το διαβάζετε σαν κείμενο ή το δίνετε σε code generator (NSwag, OpenAPI Generator, Kiota). Ξεκινά με τη ροή και τις σημαντικές σημειώσεις. Κάθε πεδίο με κωδικό της ΑΑΔΕ έχει τις επιτρεπτές τιμές με την περιγραφή τους.
• Η συλλογή Postman έχει όλες τις κλήσεις, οργανωμένες σε σενάρια, με εξηγήσεις και έτοιμα tests.

Postman σε 3 βήματα

1. Στο Postman: Import → σύρετε το αρχείο της συλλογής.

2. Ανοίξτε τη συλλογή → καρτέλα Variables και συμπληρώστε:

   Μεταβλητή	Provider API	Onboarding API
   apiKey	Το δοκιμαστικό API key σας (πού το βρίσκω)	Το ίδιο κλειδί
   issuerVat	Ο ΑΦΜ με τον οποίο γραφτήκατε	—
   vatNumber	—	Ο ΑΦΜ του πελάτη που ενεργοποιείτε
   b2gApiKey	Μόνο για B2G: το ξεχωριστό κλειδί B2G	—

3. Τρέξτε τον φάκελο 1 της συλλογής, ένα αίτημα τη φορά, με τη σειρά.

Το baseUrl δείχνει εξ ορισμού στο δοκιμαστικό (https://provider-dev.timologisi.online). Για παραγωγή το αλλάζετε σε https://provider.timologisi.online.

Δεν χρειάζεται να αλλάζετε ημερομηνία και ΑΑ

Στο Provider API η συλλογή βάζει μόνη της τη σημερινή ημερομηνία ({{today}}) και νέο ΑΑ ({{aa}}) πριν από κάθε κλήση. Τα MARK, τα UID και τα tokens που χρειάζονται τα επόμενα βήματα αποθηκεύονται αυτόματα. Στο Console του Postman βλέπετε το statusCode, το MARK και τα σφάλματα της ΑΑΔΕ κάθε απάντησης.

Τα σενάρια του Provider API

Φάκελος	Τι δοκιμάζει	Με σειρά
1. Ροή: το πρώτο παραστατικό	Credits → απόδειξη 11.1 → αναζήτηση → PDF → myDATA XML	✔
2. Τιμολόγια & αποδείξεις	1.1, 2.1, 11.2, 3.1, 8.2, φόροι ανά γραμμή και σε επίπεδο παραστατικού
3. Πιστωτικά	Τιμολόγιο → 5.1 που το πιστώνει · 5.2 · 11.4	✔
4. Κάρτα / IRIS μέσω POS	Υπογραφή Παρόχου → ολοκλήρωση · εξόφληση παλιού τιμολογίου με κάρτα · 8.4 · 8.5	✔
5. Εστίαση (8.6)	Παραγγελία → ακύρωση είδους → ανοιχτά τραπέζια → κλείσιμο με 11.1 · ολική ακύρωση	✔
6. Διακίνηση	Τιμολόγιο / απόδειξη - δελτίο αποστολής · 9.3 → τιμολόγιο που το κλείνει · ακύρωση δελτίου	✔
7. B2G (Δημόσιο)	6 τιμολόγια προς φορείς (χρειάζεται b2gApiKey)
8. OSS	11.1 σε καταναλωτή άλλου κράτους μέλους
9. Σενάρια σφαλμάτων	401 χωρίς κλειδί · 400 λάθος σύνολο πληρωμών · 228 διπλότυπο	✔

Για το Onboarding API, η ροή και τα σενάρια περιγράφονται στο Πώς λειτουργεί.

Όλη η συλλογή με μία εντολή

Με το Runner του Postman, ή με το Newman στο CI σας, τρέχετε όλα τα σενάρια με τη σειρά:

newman run Novus_Provider_API.postman_collection.json \
  --env-var apiKey=ΤΟ_ΚΛΕΙΔΙ_ΣΑΣ --env-var issuerVat=ΤΟΝ_ΑΦΜ_ΣΑΣ

Χωρίς b2gApiKey ο φάκελος 7 αποτυγχάνει, κάτι αναμενόμενο.

Έτοιμα JSON

Κάθε αρχείο είναι έγκυρο request για το SendInvoices (ή το SendInvoicesB2G). Τα ποσά, ο ΦΠΑ, τα σύνολα και οι χαρακτηρισμοί ελέγχονται αυτόματα σε κάθε έκδοση της τεκμηρίωσης. Πριν τα στείλετε, αλλάξτε τον ΑΦΜ εκδότη, το issueDate και το aa.

Κατηγορία	Αρχεία	Οδηγός
Τιμολόγια & αποδείξεις	1.1 · 2.1 · 3.1 · 8.2 · 11.1 · 11.2	Τιμολόγια & αποδείξεις
Πιστωτικά	5.1 · 5.2 · 11.4	Πιστωτικά
Φόροι	Ανά γραμμή · Σε επίπεδο παραστατικού	Φόροι, τέλη, κρατήσεις
Κάρτα / IRIS	11.1 με κάρτα · Ολοκλήρωση · 8.4 · 8.5	Πληρωμή με κάρτα / IRIS
Εστίαση	Παραγγελία · Ακύρωση είδους · Κλείσιμο 11.1 · Ολική ακύρωση	Εστίαση
Διακίνηση	1.1 - Δελτίο · 11.1 - Δελτίο · 9.3 · 1.1 που κλείνει δελτία	Διακίνηση
B2G	1.1 · 1.1 απαλλαγή ΦΠΑ · 1.1 καύσιμα · 1.1 - Δελτίο · 2.1 · 5.2	Δημόσιο (B2G)
OSS	11.1 OSS	OSS
Onboarding	Νέα αίτηση · Νέο webhook	Onboarding API

Δοκιμαστικά στοιχεία

Οι επωνυμίες, τα emails και τα MARK στα παραδείγματα είναι εικονικά. Ο 123456789 είναι ο δικός σας ΑΦΜ εκδότη: αλλάξτε τον.