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

Κάθε endpoint εκτός από το Authentication το ίδιο απαιτεί ένα JWT access token, το οποίο στέλνεται σε κάθε request ως:

Authorization: Bearer <accessToken>

Τι θα κάνετε

Ανταλλάξτε τα διαπιστευτήρια Εργάνη σας για ένα access token (διάρκεια ζωής 3 ωρών) και ένα refresh token (διάρκεια ζωής 7 ημερών). Χρησιμοποιήστε το access token σε κάθε request. Ανανεώστε το με το refresh token πριν λήξει — μην αυθεντικοποιείστε ξανά με διαπιστευτήρια σε κάθε κλήση.

Request

POST /Authentication
Content-Type: application/json

{
  "Username": "myusername",
  "Password": "mypassword",
  "Usertype": "02"
}

Πεδίο	Τιμή
Username / Password	Τα διαπιστευτήρια Εργάνη (e-ΕΦΚΑ) σας.
Usertype	"02" για σχεδόν όλες τις ενσωματώσεις — σύνδεση με διαπιστευτήρια Εργάνη. Δείτε παρακάτω για τις άλλες τιμές.

Άλλες τιμές Usertype

Τιμή	Σημασία
01	Εξωτερική σύνδεση
02	Σύνδεση με διαπιστευτήρια Εργάνη (προεπιλογή — χρησιμοποιήστε αυτή)
03	Σύνδεση για διαπιστευτήρια εργοτάξιων μέσω e-ΕΦΚΑ

cURL

curl -s -X POST \
  "https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "myusername",
    "Password": "mypassword",
    "Usertype": "02"
  }'

Node.js

const response = await fetch(
  "https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      Username: "myusername",
      Password: "mypassword",
      Usertype: "02",
    }),
  }
);

const auth = await response.json();
console.log(auth.accessToken);

PHP

<?php

$ch = curl_init("https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "Username" => "myusername",
    "Password" => "mypassword",
    "Usertype" => "02",
]));

$response = curl_exec($ch);
curl_close($ch);

$auth = json_decode($response, true);
echo $auth["accessToken"];

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessTokenExpired": 10800,
  "refreshToken": "pnFB5Vdno3pd/YgkzBjDdn+Vxe29b5I+eTLSWD8cbWk=",
  "refreshTokenExpired": "2024-05-11T09:43:37.5388855+03:00"
}

Πεδίο	Περιγραφή
accessToken	Στείλτε το σε Authorization: Bearer <accessToken> σε κάθε άλλο request.
accessTokenExpired	Διάρκεια ζωής του access token σε δευτερόλεπτα (10800 = 3 ώρες).
refreshToken	Χρησιμοποιήστε το για να αποκτήσετε νέο access token χωρίς να ξαναστείλετε διαπιστευτήρια — δείτε παρακάτω.
refreshTokenExpired	Χρονοσφραγίδα λήξης (ISO 8601) του refresh token (7 ημέρες από την έκδοση).

Αποθηκεύστε όλες τις τέσσερις τιμές. Θα χρειαστείτε το accessToken για τα requests και το refreshToken για την ανανέωσή του.

Τι μπορεί να πάει στραβά

Απάντηση	Σημασία	Διόρθωση
401 Unauthorized στο Authentication	Λάθος όνομα χρήστη, κωδικός, ή Usertype.	Ελέγξτε τα διαπιστευτήρια. Το Usertype είναι σχεδόν πάντα "02".
429 Too Many Requests	Έχετε καλέσει το Authentication (ή Refresh) πολλές φορές.	Σταματήστε να αυθεντικοποιείστε σε κάθε request — δείτε Επαναχρησιμοποιήστε τα tokens σας παρακάτω.

Ανανέωση του access token

POST /Authentication/Refresh
Content-Type: application/json

{
  "AccessToken": "<current accessToken>",
  "RefreshToken": "<current refreshToken>"
}

Επιστρέφει την ίδια δομή με το Authentication — νέο accessToken, accessTokenExpired, refreshToken, και refreshTokenExpired.

Node.js

const response = await fetch(
  "https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication/Refresh",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      AccessToken: currentAccessToken,
      RefreshToken: currentRefreshToken,
    }),
  }
);

const refreshed = await response.json();

PHP

<?php

$ch = curl_init("https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication/Refresh");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "AccessToken" => $currentAccessToken,
    "RefreshToken" => $currentRefreshToken,
]));

$response = curl_exec($ch);
curl_close($ch);

$refreshed = json_decode($response, true);

Αποσύνδεση

POST /Authentication/Logout
Content-Type: application/json

"43TD1+HMkakFt+uKDQoN+mKxttgHvSxN9S8AI+5e4kE="

Το σώμα είναι το refresh token ως απλό JSON string — όχι αντικείμενο. Η αποσύνδεση δεν διαγράφει το refresh token αμέσως· συντομεύει την υπόλοιπη διάρκεια ζωής του στις 3 ώρες. Επιστρέφει 200 OK χωρίς σώμα.

Επαναχρησιμοποιήστε τα tokens σας — μην αυθεντικοποιείστε ξανά σε κάθε request

Αυτό είναι το #1 λάθος ενσωμάτωσης

Η κλήση του Authentication (ή του Authentication/Refresh) πριν από κάθε request θα σας οδηγήσει σε rate limiting με 429 Too Many Requests.

Κάντε αυτό:

αυθεντικοποίηση μία φορά
  → αποθήκευση accessToken + refreshToken
  → χρήση accessToken σε κάθε request
  → σε 401 / api-token-expired:true, κλήση Refresh μία φορά
  → επανάληψη του request με το νέο accessToken

Όχι αυτό:

αυθεντικοποίηση → κλήση → αυθεντικοποίηση → κλήση → αυθεντικοποίηση → κλήση ...
αυθεντικοποίηση → refresh → κλήση → refresh → κλήση → refresh → κλήση ...

Ο πλήρης κύκλος ζωής του token

1. Απόκτηση: Authentication με διαπιστευτήρια → access token (3ω) + refresh token (7η).
2. Χρήση: στείλτε Authorization: Bearer <accessToken> σε κάθε request.
3. Σε 401 ή header απάντησης api-token-expired: true: καλέστε το Authentication/Refresh με το τρέχον access + refresh token, και έπειτα επαναλάβετε το αρχικό request με το νέο access token.
4. Αν το Authentication/Refresh το ίδιο επιστρέψει 401 (το refresh token έληξε μετά από 7 ημέρες): επιστρέψτε στο βήμα 1.

Τι ακολουθεί

Συνεχίστε στις Ροές Εργασίας για να στείλετε την πρώτη σας προσέλευση.