API-ul ERP Core este un set standardizat de comenzi și endpointuri disponibile în toate extensiile sale.
Swagger
Pentru testarea API-ului poate fi folosit Swagger, disponibil la adresa:
http://<PlugInIP>:<PlugInPort>/swagger/index.html
Pentru utilizarea Swagger este necesar un token valid. Solicită unul conform exemplului de mai jos, apasă Authorize în dreapta sus, introdu tokenul fără prefixul „Bearer ” și apasă Authorize.
După autorizare, poți apela din Swagger resursele protejate ale API-ului.
Autentificare
Sistemul include un server de autentificare separat, implementat ca extensie care gestionează cereri precum conectarea și deconectarea. Deși are acces și la alte resurse ale sistemului, este recomandată utilizarea sa doar în acest scop.
Serverul este identificat prin IP și PORT. Formatul endpointului API este:
http://<AuthServerIP>:5010/api/Authentication/...
Majoritatea endpointurilor necesită autentificare. Pentru apelarea unui endpoint protejat, tokenul trebuie inclus în antetul cererii, conform exemplului:
| Cheia antetului HTTP | Conținut |
| Authentication | Bearer DEMO_TOKEN (exemplu; înlocuiește cu tokenul autorizat) |
Cheia din acest exemplu istoric este „Authentication”.
Conținutul este textul „Bearer”, urmat de un spațiu și de tokenul furnizat de server.
Conectare
http://<AuthServerIP>:5010/api/Authentication/LogIn
Pentru obținerea unui token JWT valid, trimite o cerere POST serverului de autentificare.
{
"tenantName":"DemoCompany",
"password":"DEMO_VALUE",
"userName":"demo@example.invalid",
"email":"demo@example.invalid"
}
Versiunea de nucleu descrisă în acest document nu criptează parola. Documentul prevede criptare în versiuni viitoare; acest aspect trebuie luat în calcul la implementarea autentificării.
Dacă datele de autentificare sunt valide, serverul returnează un token JWT utilizabil în cererile ulterioare.
Pentru identificarea utilizatorului este suficient să trimiți userName sau email.
{
"tokenData":
{
"accessToken":"DEMO_VALUE",
"expiresAt":"2022-06-30T11:55:16+03:00",
"refreshToken":"DEMO_VALUE",
"userId":"592299e7-45c7-48dd-9ddd-6adacabdbff9",
"twoFactor":false
},
"requestStartedAt":"2022-06-23T11:55:16.8584842+03:00",
"requestFinishedAt":"2022-06-23T11:55:16.8584842+03:00",
"requestTimespan":"00:00:00.2651406",
"messages":[],
"httpStatusCode":200
}
Răspunsul de autentificare conține două tokenuri: unul de acces și unul de reîmprospătare. Tokenul de acces permite apelarea resurselor API. Tokenul de reîmprospătare permite obținerea unui nou token de acces înainte de expirare, pentru continuitatea sesiunii.
Comunicația HTTP din exemplu nu este criptată, iar tokenurile pot fi interceptate. Protejează comunicația dintre infrastructura ERP și utilizator prin SSL/TLS.
Deconectare
http://<AuthServerIP>:5010/api/Authentication/LogOut
Tokenul de acces poate fi invalidat printr-o cerere de deconectare către serverul de autentificare. Pentru deconectare trebuie transmis tokenul de reîmprospătare, astfel încât să fie evitate deconectările accidentale sau frauduloase.
{
"refreshToken":"DEMO_VALUE"
}
Serverul răspunde cu rezultatul operației și un mesaj:
{
"requestStartedAt":"2022-06-23T12:11:28.8669649+03:00",
"requestFinishedAt":"2022-06-23T12:11:28.8669649+03:00",
"requestTimespan":"00:00:00.1351662",
"messages":
[
{"messageText":"User demo@example.invalid logged out.",
"messageSeverityDescription":"Info",
"messageSeverityCode":0,
"logType":0,
"couldNotLog":false}
],
"httpStatusCode":200
}