Skip to main content

API

Oltre alle API di "base" con le quali si può richiedere un certificato e gestirne il ciclo di vita, la Certification Authority fornisce anche una API per poter effettuare contestualmente l'identificazione e il rilascio di in certificato ad un titolare.

Metodo di innesco

Per avviare la sessione di identificazione e stacco occorre utilizzare il servizio:

Identificazione e stacco

Il servizio può essere invocato solo con un token TSID di tipo API: operando quindi all'interno di un determinato cliente.

I dati da passare sono del tipo:

{
  "profileName"profile": "IE-SPID",
  "identificationProcesses": ["VIDEO", "SPID"]
  "rao": {
    "certificatePin": "PinEsempio11",
    "alias": "RAOCST00A00A002A"
  },
  "owner": {
    "firstName": "Gaio Giulio",
    "lastName": "Cesare",
    "email": "a.mariano@teamsystem.com",
    "phoneNumber": "123456487",
    "fiscalCode": "CSRGGL44L13H501E"
  },
  "webhook": {
    "url": "{{webhookUrl}}"
  }
}

dove:

  • profileNameprofile è il nome del profilo da utilizzare per l'identificazione e l'enroll
identificationProcesses è l'elenco dei processi di identificazione che voglio mettere a disposizione. La lista deve essere costituita dai processi di identificazione previsti in CA per quel dato profilo. Se il profilo ne prevede uno solo, il parametro è opzionale. rao.alias è il RAO che autorizza l'emissione del certificato rao.certificateAlias è l'alias del certificato del RAO da utilizzare. Non è obbligatorio ed ha senso solo nel caso in cui il RAO avesse più di un certificato rao.certificatePin è il pin del certificato da utilizzare owner sono i dati di base del titolare. Sono tutti obbligatori ad eccezione del codice fiscale webhook.url è l'url cui il servizio comunicherà gli esiti dell'operazione. Il webhook verrà inviato sempre in POST con una struttura minima del tipo: 
{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "CERT_CREATION_FAILED",
  "intermediate": false,
  "error": true
}
    • sessionId indica la sessione di riferimento. Serve per associare il webhook alla sessione cui si riferisce
    • status stato della sessione
    • intermediate se true indica un webhook non "finale" ma di cambio stato di passaggio
    • error se true è un webhook finale di errore altrimenti di successo
  • webhook.auth.header serve a definire l'header dove inserire un'eventuale authorization
  • webhook.auth.value è il valore di un'eventuale authorization

La risposta sarà semplicemente un json con il valore della sessione appena avviata.

In background il sistema invierà una mail all'indirizzo fornito in input per procedere con l'identificazione.

Validazione campi in input

I dati relativi al titolare devono rispettare le reg exp che si possono scaricare da qui:

Validazione

Webhook

Il sistema invierà una serie di webhook, tendenzialmente uno ad ogni cambio di stato della sessione.

Di seguito la lista completa:

{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "OPENED",
  "intermediate": true,
  "error": false
}

{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "IDENTIFICATION_STARTED",
  "intermediate": true,
  "error": false
}

{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "IDENTIFICATION_SUCCESS",
  "intermediate": true,
  "error": false
}

{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "CERT_CREATION_STARTED",
  "intermediate": true,
  "error": false
}

{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "CERT_CREATION_FAILED",
  "intermediate": false,
  "error": true
}

{
  "sessionId": "64a6ddda235a132e5e6a67ed",
  "status": "CERT_CREATION_COMPLETED",
  "intermediate": false,
  "error": false,
  "certificate": {
    "alias": "52832",
    "validFrom": "2023-07-13T13:41:00",
    "validTo": "2024-07-12T19:41:00",
    "profileName": "AUTO",
    "signaturesNumber": 0
  },
  "owner": {
    "alias": "TINIT-CSRGGL44L13H501E",
    "firstName": "Gaio Giulio",
    "lastName": "Cesare",
    "birthDate": "1944-07-13",
    "birthDistrict": "RM",
    "birthCity": "Roma",
    "birthCountry": "IT",
    "sex": "M",
    "email": "string",
    "phone": "string"
  }
}

Back to top