Autorizarea¶

Descriere - Autorizare¶

Pentru accesarea API-urilor Keez este necesară obținerea unui token de acces (bearer token), folosind fluxul OAuth 2.0 client credentials
Dat fiind faptul că aplicația permite asocierea unui cont la mai mulți clienți, apelurile către API necesită în general și specificarea unui «clientEid», un identificator al clientului și un secret, de asemenea furnizat de Keez.

Medii¶

Aplicația keez.ro pune la dispoziție două medii complet separate pentru realizarea operațiile specifice acestui API:
Staging
Este un mediu dedicat testării API-ului de facturare. Orice factură realizată în acest mediu nu are impact contabil

Atenționare

La intervale semi-regulate acest mediu este rescris. Adică toate datele (facturi, articole) vor fi șterse complet fără posibilitate de recuperare de niciun fel
Producție sau App
Este mediul de producție. Orice factură realizată în acest mediu va impacta direct contabilitatea clientului

Atenționare

Acest mediu nu este niciodată rescris. Orice articol sau factură realizată în acest mediu va rămâne permanent stocată în sistem

Atenționare

Mediile stage și prod sunt complet separate din toate punctele de vedere: locație server, aplicație online, bază de date, apeluri API API. Orice adăugare, modificare sau ștergere pe un mediu nu va avea impact asupra celuilalt

Proprietăți¶

Atenționare

Pentru procurarea următoarelor proprietăți necesare, vă rugăm să contactați firma Keez.ro

Proprietăți necesare la apelul API-ului pentru obținerea token-ului de autorizare:

client_eid

este un identificator extern pentru compania care folosește API-ul
fiecare client primește un identificator unic
este oferit de un reprezentant https://keez.ro/

application_id

este un identificator al aplicației
este oferit de un reprezentant https://keez.ro/

secret

este o parolă
este oferit de un reprezentant https://keez.ro/

Notă

Pentru a înțelege mai bine aceste proprietăți, dacă am extrapola acest API la o pagină de login din zilele noastre, acestea ar putea fi definite astfel:

client_eid = name

application_id = user

secret = password

Preluarea unui token¶

Preluarea unui token se realizează prin operația de POST

URL-ul de acces token este: https://{MEDIU}.keez.ro/idp/connect/token

De observat proprietatea {MEDIU} din URL, aceasta se va înlocui cu MEDIU pentru care se face apelul:

Pentru Staging: https://staging.keez.ro/idp/connect/token

Pentru Producție: https://app.keez.ro/idp/connect/token

Proprietățile de mai sus (client_eid, application_id, secret) vor fi servite către API sub formă de request body

Rezultatul API-ului este de tip JSON, din care se vor extrage informațiile necesare: Vezi Model Autorizare

Token-ul are un termen de expirare de 60 minute. Pentru folosirea API-ului este recomandată obținerea unui nou Token atunci cand cel vechi expiră. Vezi: Exemple Autorizare

Atenționare

De remarcat particularitatea adăugării prefixului «app» la valoarea parametrului «application_id» pentru câmpul «client_id». Vezi exemplul

Exemple Autorizare¶

Preluare Token varianta simplă fără reîmprospătare token (refresh automat la expirare):

Această metodă se folosește atunci când se realizează o operație punctuală, cu durată scurtă.

import requests

class TokenService:
    def __init__(self):
        self.token_url = 'https://staging.keez.ro/idp/connect/token'

        self.client_eid = '{RECEIVED_CLIENT_EID}'
        self.application_id = '{RECEIVED_APPLICATION_ID}'
        self.secret = '{RECEIVED_SECRET}'

    def generate_token(self):
        req = requests.post(self.token_url, data={
            'client_id': f'app{self.application_id}',
            'client_secret': self.secret,
            'grant_type': 'client_credentials',
            'scope': 'public-api',
        }, headers={
            'Content-Type': 'application/x-www-form-urlencoded'
        })
        req.raise_for_status()
        return req.json()


if __name__ == '__main__':
    token = TokenService()
    auth_token = token.generate_token()
    print(auth_token)

Preluare Token varianta complexă cu expirare token și refresh automat al token-ului:

Este cea mai sigură metodă, deoarece se bazează direct pe monitorizarea timpului de expirare al token-ului
De fiecare dată când token-ul expiră, acesta se reîmprospătează

import time
import requests
import python_jwt as jwt


class TokenService:
    def __init__(self):
        self.token_url = 'https://staging.keez.ro/idp/connect/token'

        self.client_eid = '{RECEIVED_CLIENT_EID}'
        self.application_id = '{RECEIVED_APPLICATION_ID}'
        self.secret = '{RECEIVED_SECRET}'

        self.expires = None
        self.token = None
        self.expires = time.gmtime(0)

    def refresh_auth_token(self):
        if self.token_expired():
            self.generate_token()

    def token_expired(self):
        return self.expires < time.gmtime()

    def generate_token(self):
        req = requests.post(self.token_url, data={
            'client_id': f'app{self.application_id}',
            'client_secret': self.secret,
            'grant_type': 'client_credentials',
            'scope': 'public-api',
        }, headers={
            'Content-Type': 'application/x-www-form-urlencoded'
        })
        req.raise_for_status()
        json = req.json()

        self.token = f'{json["token_type"]} {json["access_token"]}'
        (_, claims) = jwt.process_jwt(json['access_token'])
        self.expires = time.gmtime(claims['exp'])

        return


if __name__ == '__main__':
    token = TokenService()
    token.refresh_auth_token()