Firma con OTP

La firma con OTP si può realizzare avendo a disposizione due tipologie di certificati:

certificato longterm
certificato oneshot

Flusso

Recupero certificati

Per firmare occorre richiedere un certificato di firma AUTO o SEAL in stato READY per un dato titolare. Per farlo si usa il seguente servizio

INFO	VALUE	NOTES
METHOD	GET
URL	"$baseUrl/api/v1/certificate"
QUERY PARAM	ownerAlias	Obbligatorio, indica l'alias del titolare del certificato
QUERY PARAM	size	Non obbligatorio, dimensione della pagina. Def 20
QUERY PARAM	sort	Non obbligatorio, indica il sorting desiderato. Es. sort=id,desc
QUERY PARAM	withPem	Non obbligatorio, flag per indicare se ritornare anche il PEM del certificato
QUERY PARAM	status	Non obbligatorio, indica lo stato desiderato. Valori possibili READY, SUSPENDED, REVOKED
QUERY PARAM	profiles	Non obbligatorio, indica i profili desiderati. Valori possibili AUTO, SEAL, ONESHOT, FEQ

Esempio chiamata

curl --location 'https://ca-test.teamsystem.cloud/api/v1/certificate?ownerAlias=TINIT-MRNNTN78E12G751H&profiles=ONESHOT%2CFEQ&status=READY&withPem=true&pinBlocked=false&size=10&page=0&sort=id%2Cdesc' \
--header 'Authorization: ••••••'

Esempio risposta

{
    "content": [
        {
            "alias": "1219483",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "4790ee0147e6e742",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPj......Iyh/zg=",
            "validFrom": "2025-10-21T00:06:00Z",
            "validTo": "2028-10-20T18:06:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1217426",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "064251a1935ff5c9",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPjCC....KbGuR3I=",
            "validFrom": "2025-10-19T00:04:00Z",
            "validTo": "2028-10-18T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1214450",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "25a17f4cc9427ec3",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIP....jwiERBb0M=",
            "validFrom": "2025-10-17T00:04:00Z",
            "validTo": "2028-10-16T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1211014",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "5e7e60f07f753ff8",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPj......CtHI=",
            "validFrom": "2025-10-15T00:04:00Z",
            "validTo": "2028-10-14T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1210088",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "5a941d335cdff3b8",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPjC.....HNV8Rho=",
            "validFrom": "2025-10-14T13:13:00Z",
            "validTo": "2028-10-14T07:13:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1210047",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "420ef898d0f48083",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIP.....AryQ=",
            "validFrom": "2025-10-14T13:08:00Z",
            "validTo": "2028-10-14T07:08:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1207207",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "101b209d5c6028cb",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPjC......mLKppUVg+l4KSkg9LL8R7GfCtUG1mEJ6EfWybwpTp/df/lFmqmyPzK4=",
            "validFrom": "2025-10-13T00:04:00Z",
            "validTo": "2028-10-12T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1205279",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "6893d84de6377566",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPjCCBi......4vJMre8=",
            "validFrom": "2025-10-11T00:04:00Z",
            "validTo": "2028-10-10T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1202634",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "25d91c81e3f2e6dc",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPj......F9eXc=",
            "validFrom": "2025-10-09T00:04:00Z",
            "validTo": "2028-10-08T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        },
        {
            "alias": "1198787",
            "profile": {
                "type": "FEQ",
                "identificationProcess": "CIE"
            },
            "serialNumber": "6bb60490a0d1154b",
            "customerName": "K6 Customer 01",
            "phoneNumber": "+393452495944",
            "email": "a.mariano@teamsystem.com",
            "enabled": true,
            "status": "READY",
            "pem": "MIIIPjC.....h9YOolaH9TA=",
            "validFrom": "2025-10-07T00:04:00Z",
            "validTo": "2028-10-06T18:04:00Z",
            "owner": {
                "identityType": "PF",
                "alias": "TINIT-MRNNTN78E12G751H",
                "firstName": "Antonio",
                "lastName": "Mariano"
            },
            "hasPin": true,
            "pinBlocked": false,
            "signatureProcesses": []
        }
    ],
    "number": 0,
    "numberOfElements": 10,
    "totalElements": 49,
    "totalPages": 5
}

Apertura sessione

Una volta otteneuto il certificato da utilizzare, è necessario aprire una sessione di firma.

INFO	VALUE	NOTES
METHOD	POST
URL	$baseUrl/api/v1/signature/open/$aliasTitolare
PATH PARAM	aliasTitolare	Obbligatorio, indica l'alias del titolare del certificato

Esempio chiamata

curl --location 'https://ca-test.teamsystem.cloud/api/v1/signature/open/TINIT-MRNNTN78E12G751H' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "certificateAlias": 1219483, //alias del certificato da usare. Se non fornito, si userà il più recente.
  "strongAuth": "SMS_OTP",
  "maxSignatures": 10 //numero di firme che può essere fatto in questa sessione
}'

Esempio risposta

{
    "id": "68f8f40810153d7b9c4e2a7f",
    "certificateAlias": "1219483",
    "signatureTimeout": "PT5M", //timeout dell'intera operazione di firma
    "strongAuthTimeout": "PT10M", //timeout della sola operazione di strong auth (invio e validazione OTP)
    "strongAuth": "SMS_OTP",
    "maxSignatures": 10, //numero massimo di hash che si possono firmare in questa sessione
    "completedSignatures": 0, //firme già effettuate
    "status": {
        "value": "OPENED" //stato della sessione. In fase di apertura sempre a OPENED
    },
    "createdAt": "2025-10-22T15:11:04.128812807Z",
    "updatedAt": "2025-10-22T15:11:04.128812807Z",
    "version": 0
}

Invio SMS

Aperta la sessione, occorre richiedere l'invio dell'SMS

INFO	VALUE	NOTES
METHOD	POST
URL	$baseUrl/api/v1/signature/sms-otp/send/$sessionId
PATH PARAM	sessionId	Obbligatorio, sessione aperta nello step precedente

Esempio chiamata

curl --location --request POST 'https://ca-test.teamsystem.cloud/api/v1/signature/sms-otp/send/68f8f40810153d7b9c4e2a7f' \
--header 'Authorization: ••••••' \
--data ''

Esempio risposta

{
    "remaining": 3 //numero di tentativi di invii rimasti
}

remanining è il numero di volte che si può ancora tentare l'invio dell'OTP senza invalidare la sessione

Validazione OTP

INFO	VALUE	NOTES
METHOD	PUT
URL	/api/v1/signature/sms-otp/validate/$sessionId
PATH PARAM	sessionId	Obbligatorio, sessione aperta nello step precedente

Esempio chiamata

curl --location --request PUT 'https://ca-test.teamsystem.cloud/api/v1/signature/sms-otp/validate/68f8f40810153d7b9c4e2a7f' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "otp": "316902"
}'

Firma

INFO	VALUE	NOTES
METHOD	PUT
URL	$baseUrl/api/v1/signature/sign/$sessionId
PATH PARAM	sessionId	Obbligatorio, indica la sessione aperta al punto prima

Gli hash firmati saranno restituiti nello stesso ordine di come sono stati forniti in input.

Esempio chiamata

curl --location --request PUT 'https://ca-test.teamsystem.cloud/api/v1/signature/sign/68f8f40810153d7b9c4e2a7f' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "certificatePin": "11223344", //pin del certificato
    "hashes": [ //hash da firmare
    "myMXwslBoXkTDQ0olhq1QsiHRWWL4yj1V0IuoK+PYOg="
  ]
}'

Esempio risposta

{
    "signedHashes": [
        "NQORY//Z6ZSNZNS5CviSD5VX9Pp6sEkNV9Xl+2PziN0G8cmORiJPKA1W0Yt85HX66xoNODoU+pkI7Uc9ck2b8hype7qSW+aASmasReIa6JvgdRFd1J/wR/qpE7087te0WTc5HvytNp3aB17Kii0yvDvL3NrTkqddgdsZNx1k3OFrkqPIc+N8AOmCvNrkyMXwdrqJFZpUxWsTHFj87Gk90EwLmlxhRiGCKjuF2Pnhlu+BWizqSN3dt6+j5kziHzEj/4zxaWLEXKGQg1shfm4rRQl8qsU9it3uLtqIydGMYrk6CFeg5pbxzB7qBQj9UCQtBT2ZiDKvWEm1IzVrNM2vsA=="
    ],
    "maxSignatures": 10,
    "completedSignatures": 1
}

Flusso​

Recupero certificati​

Apertura sessione​

Invio SMS​

Validazione OTP​

Firma​

Flusso

Recupero certificati

Apertura sessione

Invio SMS

Validazione OTP

Firma