Skip to main content

Οδηγός Παραγωγικής Χρήσης

Πριν στρέψετε αυτή την ενσωμάτωση στο παραγωγικό περιβάλλον (https://eservices.yeka.gr/WebservicesAPI/Api/), βεβαιωθείτε ότι ο κώδικάς σας κάνει τα πέντε παρακάτω. Καθένα βασίζεται σε τεκμηριωμένη συμπεριφορά του Εργάνη — καμία επινοημένη εγγύηση.

1. Στρατηγική ανανέωσης token​

Τα access tokens διαρκούν 3 ώρες (accessTokenExpired: 10800). Τα refresh tokens διαρκούν 7 ημέρες.

Κάντε αυτό:

  • Αποθηκεύστε accessToken, refreshToken, και refreshTokenExpired μαζί με κάθε σύνολο διαπιστευτηρίων που διαχειρίζεστε.
  • Σε κάθε κλήση API, ελέγξτε αν το access token πλησιάζει στη λήξη του (π.χ. ανανεώστε προληπτικά αν έχουν περάσει περισσότερα από 2ω45λ από την έκδοσή του) — ή απλά καλέστε το Authentication/Refresh αντιδραστικά όταν ένα request επιστρέφει 401 / api-token-expired: true, και επαναλάβετε μία φορά.
  • Αν το Authentication/Refresh το ίδιο επιστρέψει 401, το refresh token έχει λήξει (7 ημέρες) — καλέστε ξανά το Authentication με διαπιστευτήρια.

Μην κάνετε αυτό:

2. Όριο ρυθμού (Rate limiting)​

Το μόνο τεκμηριωμένο όριο ρυθμού είναι στις κλήσεις αυθεντικοποίησης (429 Too Many Requests). Δεν υπάρχει τεκμηριωμένο όριο ανά λεπτό στο ίδιο το Documents/WRKCardSE, αλλά η διόρθωση για το 429 είναι η ίδια και στις δύο περιπτώσεις: επαναχρησιμοποιήστε το access token σας στα requests αντί να αυθεντικοποιείστε ξανά.

3. Αποφυγή διπλοεγγραφών (Idempotency)​

Το Εργάνη δεν έχει μηχανισμό idempotency-key

Δεν υπάρχει request ID ή header idempotency που σας επιτρέπει να "επαναλάβετε με ασφάλεια την ίδια ακριβώς υποβολή" και να πάρετε το ίδιο ακριβώς αποτέλεσμα πίσω. Κάθε δεκτό POST επιστρέφει ένα νέο protocol, ακόμα και αν το payload είναι ίδιο με προηγούμενο request.

Αυτό που το Εργάνη εγγυάται (δείτε Επαναλαμβανόμενα γεγονότα για τον ίδιο εργαζόμενο και ημέρα): για ένα δεδομένο f_afm + f_reference_date + f_type, το πιο πρόσφατα υποβληθέν γεγονός είναι αυτό που μετράει στο Ημερολόγιο Πραγματικής Απασχόλησης. Προηγούμενες υποβολές για τον ίδιο συνδυασμό δεν διαγράφονται, αλλά σταματούν να είναι έγκυρες.

Πρακτική στρατηγική αποφυγής διπλοεγγραφών:

  1. Πριν την υποβολή, ελέγξτε αν έχετε ήδη αποθηκευμένο protocol για αυτό το ακριβές γεγονός (ίδιος εργαζόμενος, ημερομηνία αναφοράς, και τύπος γεγονότος) από αυτή την εκτέλεση.
  2. Αν ναι, μην το υποβάλετε ξανά — έχετε ήδη επιβεβαιωμένο αποτέλεσμα.
  3. Αν δεν είστε σίγουροι αν ένα προηγούμενο request πέτυχε (π.χ. μετά από σφάλμα δικτύου), είναι ασφαλές να υποβάλετε ξανά το ίδιο γεγονός: ο Εργάνη θα το καταγράψει ξανά με νέο protocol, και επειδή έχει το ίδιο f_type + f_reference_date + f_afm, απλά γίνεται η έγκυρη τιμή (που, αν τα δεδομένα σας δεν άλλαξαν, είναι ούτως ή άλλως το σωστό αποτέλεσμα). Δείτε Αποτυχία δικτύου κατά το request.

Μη φτιάξετε δικό σας επίπεδο idempotency που αποτρέπει την επανυποβολή σε περίπτωση αβεβαιότητας — ο κανόνας "το πιο πρόσφατο κερδίζει" του Εργάνη κάνει ήδη την επανυποβολή ασφαλή για αυτή τη συγκεκριμένη μορφή γεγονότος.

4. Απαιτήσεις καταγραφής (Logging)​

Για κάθε υποβολή, καταγράψτε:

ΠεδίοΓιατί
Payload request (Cards.Card[].Details.CardDetails[])Αναπαραγωγή του τι στάλθηκε σε περίπτωση διαφωνίας.
protocol (σε επιτυχία)Απαραίτητο για ανάκτηση του PDF αργότερα μέσω GET Documents/WRKCardSE?protocol=...&submittedDate=.... Αυτό είναι το audit trail σας.
submitDate (σε επιτυχία)Πότε το κατέγραψε το Εργάνη — συγκρίνετε με το f_date για να επιβεβαιώσετε ότι ήταν εμπρόθεσμο.
message (σε αποτυχία)Ο ακριβής λόγος απόρριψης — απαραίτητος για υποστήριξη/debugging.

Χωρίς καταγεγραμμένο protocol, δεν μπορείτε να αποδείξετε ότι ένα συγκεκριμένο γεγονός έγινε δεκτό.

5. Το παράθυρο 15 λεπτών καθορίζει το budget επαναλήψεών σας​

Κάθε προσέλευση/αποχώρηση πρέπει να φτάσει στον Εργάνη εντός 15 λεπτών (± 1 λεπτό) από το f_date για να είναι εμπρόθεσμη. Αυτό έχει δύο πρακτικές συνέπειες:

  • Υποβάλετε αμέσως, μην κάνετε batch. Αν το σύστημά σας ουρές γεγονότα και τα στέλνει σε παρτίδες κάθε 30 λεπτά, κάθε γεγονός θα είναι εκπρόθεσμο, και τα εκπρόθεσμα γεγονότα απαιτούν κωδικό αιτιολόγησης που (σύμφωνα με Εκπρόθεσμες & δικαιολογημένες υποβολές) καλύπτει μόνο ανωτέρα βία — όχι "κάνουμε batch".
  • Ενσωματώστε επαναλήψεις σε αυτό το budget 15 λεπτών. Αν μια υποβολή αποτύχει λόγω 401/ληγμένου token, ανανεώστε και επαναλάβετε αμέσως — έχετε λεπτά, όχι ώρες, πριν το γεγονός γίνει εκπρόθεσμο.

Αν οι συσκευές σας είναι μερικές φορές offline για περισσότερο από 15 λεπτά, διαβάστε Αποτυχία δικτύου κατά το request για το πώς να χειριστείτε τις εκπρόθεσμες υποβολές που προκύπτουν με ειλικρίνεια.

Τι ακολουθεί​

Τα Πραγματικά Σενάρια καλύπτουν τις περιπτώσεις αποτυχίας για τις οποίες σας προετοιμάζει αυτός ο οδηγός.