[Apertura sessione](https://ca-test.agyo.io/openapi/swagger-ui/index.html?urls.primaryName=strong-auth-signature-core#/token%20API/open_1 "Apertura sessione")
I dati da fornire sono: - **l'alias dell'owner** per cui firmare in path param - il body seguente ```JSON { "certificateAlias": "123", "strongAuth": "type", "maxSignatures": n, "webhook": { "url": "url" } } ``` dove: - **certificateAlias** è il certificato da utilizzare. Il certificato DEVE essere un certificato che appartiene all'owner indicato **E** al customer relativo al token. Non è obbligatorio. - **strongAuth** è il tipo di strong authentication prevista. I valori possibili sono: - SMS\_OTP: strong auth tramite otp inviato per sms - PHONE\_CALL: strong auth tramite chiamata telefonica - **maxSignatures** è il numero di firme che si vogliono effettuare nella sessione - **webhookUrl** è l'url, opzionale, del webhook su cui si possono ricevere i cambi stato della firma. Tale webhook verrà utilizzato in base al tipo di strong auth: es. l'SMS\_OTP non lo prevede, PHONE\_CALL sì. In ritorno si ottiene la sessione appena aperta con le seguenti info: ```JSON { "id": "64a19ba4ba848a71caae31d8", "certificateAlias": "44040", "signatureTimeout": "PT10M", "strongAuthTimeout": "PT5M", "strongAuth": "SMS_OTP", "maxSignatures": 20, "completedSignatures": 0, "status": { "value": "OPENED", "step": null, "remaining": null }, "createdAt": "2023-07-02T15:45:40.025663395", "lastModifiedAt": "2023-07-02T15:45:40.025663395" } ``` dove: - **id** è l'id della sessione appena aperta. Da utilizzare nelle chiamate successive - **certificateAlias** è l'alias del certificato che si userà per la firma - **strongAuth** indica la tipologia di strong authentication che si userà - **maxSignatures** è il numero di firme massimo che si può firmare in questa sessione - **completedSignatures** indica le firme completate nella sessione. All'inizio sarò sempre zero - **createdAt** e **lastModifiedAt** sono le date di inserimento e ultimo aggiornamento - **signatureTimeout** indica il timeout della intera sessione di firma. E' un valore configurabile - **strongAuthTimeout** indica il timeout della fase di strong authentication. E' un valore configurabile - **status** indica lo stato della sessione. Appena creata sarò sempre in stato **OPENED** A questo punto si procede in base alla tipologia di strong auth prevista dalla sessione. #### **1. SMS\_OTP** ##### **Invio otp** Occorre inviare un OTP tramite il servizio[Invio OTP API](https://ca-test.agyo.io/openapi/swagger-ui/index.html?urls.primaryName=strong-auth-signature-otp#/AUTHORITY_API/send "Invio OTP API")
fornendo in path param l'id di sessione ritornato al punto precedente. L'invio dell'sms porta la sessione in stato: ```json "status": { "value": "STRONG_AUTH", "step": "SEND_SMS", "remaining": 2 } ``` dove: - **value** indica che siamo passati nello stato di strong authentication - **step** indica che ci troviamo nello step di sms inviato - **reamining** indica quante volte ancora potremmo chiamare questo servizio per riinviare l'otp ##### **Validazione otp** Occorre validare l'OTP[Validazione OTP API](https://ca-test.agyo.io/openapi/swagger-ui/index.html?urls.primaryName=strong-auth-signature-otp#/AUTHORITY_API/validate "Validazione OTP")
fornendo in path param l'id di sessione ritornato al punto precedente e l'otp inviato nel body. La validazione dell'otp in caso di successo porta la sessione a **READY\_TO\_SIGN**, altrimenti lo stato diventa: ```json "status": { "value": "STRONG_AUTH", "step": "OTP_VALIDATION", "remaining": 2 } ``` dove: - **value** indica che siamo passati nello stato di strong authentication - **step** indica che ci troviamo nello step di validazione otp - **reamining** indica quante volte ancora potremmo chiamare questo servizio per validare l'otp Se la validazione dell'otp non viene completata nonostante i tentativi a disposizione, lo stato della sessione diventa: ```json "status": { "value": "FAILED", "step": "OTP_VALIDATION", "remaining": 0 } ``` #### **2. PHONE\_CALL** ##### **Avvio chiamata** Occorre avviare la chiamata tramite il servizio[Avvio chiamata API](https://ca-test.agyo.io/openapi/swagger-ui/index.html?urls.primaryName=strong-auth-signature-phone#/AUTHORITY_API/ingoing "Avvio chiamata")
fornendo in path param l'id di sessione ritornato al punto precedente. Dopo l'avvio della chiamata, i cambi di stato della sessione verranno comunicati all'integratore tramite webhook. L'avvio della chiamata porterà la sessione in stato: ```json "status": { "value": "STRONG_AUTH", "step": "PHONE_CALL_OPENING" } ``` dove: - **value** indica che siamo passati nello stato di strong authentication - **step** indica che ci troviamo nello step di sms inviato Da questo momento in poi la sessione subirà delle modifiche in base all'andamento dell'operazione: Se il chiamante esegue la chiamata al numero verde riportato lo stato diventerà: ```json "status": { "value": "STRONG_AUTH", "step": "PHONE_CALL_WAITING_PIN" } ``` per indicare che il sistema attende l'immissione del pin di firma. A pin inserito la sessione passerà in **READY\_TO\_SIGN** per indicare che si è pronti per la firma. #### **Firma hashes** Una volta completata la strong auth, la sessione si troverà in stato **READY\_TO\_SIGN**, cioè pronta per la firma. Solo a questo punto sarò possibile chiamare il servizio:[Firma API](https://ca-test.agyo.io/openapi/swagger-ui/index.html?urls.primaryName=strong-auth-signature-core#/token%20API/signature "Firma")
con i seguenti valori: - **id sessione** in path param - il body seguente ```JSON { "certificatePin": "12345678", "hashes": [ "myMXwslBoXkTDQ0olhq1QsiHRWWL4yj1V0IuoK+PYOg=" ] } ``` - **certificatePin** è il pin del certificato da utilizzare, sempre che il certificato ne preveda uno. - **hashes** è la collection di hashes in base64 da firmare. Gli hash devono essere in base64 e ottenuti con algoritmi consentiti dalla CA[Recupero sessione API](https://ca-test.agyo.io/openapi/swagger-ui/index.html?urls.primaryName=strong-auth-signature-core#/token%20API/get "Recupero sessione")