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 e operando quindi all'interno di un determinato cliente.

I dati da passare sono del tipo:

{
  "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",
    "sex"; "M"
  },
  "webhook": {
    "url": "webhookUrl"
  }
}

dove:

• profile è 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.

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.
La mail conterrà un url relativo ad una UI che guiderà il futuro titolare attraverso gli step di identificazione e rilascio del certificato.

Webhook

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

Il webhook verrà inviato sempre in POST con una struttura minima del tipo:

{
  "success": true,
  "traceId": "c03b592fe3a3d05e6a60f1fcd809f0b7",
  "id": "651fb390d2cdf479208d7533",
  "context": "IDENTIFICATION_ENROLL",
  "event": "SESSION_OPENED",
  "data": {
    "intermediate": true
  }
}

• • id indica la sessione di riferimento. Serve per associare il webhook alla sessione cui si riferisce
  • traceId serve per troubleshooting
  • success indica se si tratta di un evento di errore (false) o meno (true)
  • context è il contesto da cui arriva l'evento e sarà sempre IDENTIFICATION_ENROLL
  • event è l'evento lanciato
  • data conterrà dati dell'evento
    • intermediate sarà a true se si tratta di un evento intermedio

Di seguito la lista completa:

## EVENTO INIZIALE DI APERTURA SESSIONE
{
  "success": true,
  "traceId": "bf6c7c76e895faace1bb78e1c90a1d87",
  "id": "655caea6d70afb2cca0f13fa",
  "context": "IDENTIFICATION_ENROLL",
  "event": "SESSION_OPENED",
  "data": {
    "intermediate": true
  }
}


## EVENTO DI IDENTIFICAZIONE COMPLETATA CON ERRORE
{
  "success": false,
  "traceId": "999ea355bf8d1ab275e4808b56b3d0c5",
  "id": "651fb390d2cdf479208d7533",
  "context": "IDENTIFICATION_ENROLL",
  "event": "IDENTIFICATION",
  "data": {
    "intermediate": false,
    "code": "IDN_008",
    "detail": "External provider identification failed"
  }
}

## EVENTO DI IDENTIFICAZIONE COMPLETATA CON SUCCESSO
{
  "success": true,
  "traceId": "86f72deb36ab999dd31806598cc05a16",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "IDENTIFICATION",
  "data": {
    "intermediate": true
  }
}

## EVENTO DI COMPLETAMENTO RACCOLTA DATI DALL'UTENTE
{
  "success": true,
  "traceId": "4be434fa8b3599d21d8259e4af7c6e63",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "USER_SUBMITTED_DATA",
  "data": {
    "intermediate": true
  }
}

## EVENTO DI AVVIO RICHIESTA CERTIFICATO
{
  "success": true,
  "traceId": "3f9da6511cc1c56284907c409e74a2a0",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "CERT_OPENED",
  "data": {
    "intermediate": true
  }
}

## EVENTO DI COMPLETAMENTO CON SUCCESSO EMISSIONE CERTIFICATO
{
  "success": true,
  "traceId": "3f9da6511cc1c56284907c409e74a2a0",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "CERT_EMITTED",
  "data": {
    "intermediate": false,
    "certificate": {
      "alias": "72822",
      "validFrom": "2023-10-06T07:53:00",
      "validTo": "2028-10-05T07:53:00",
      "signaturesNumber": 0
    },
    "owner": {
      "alias": "TINIT-CSRGGL44L13H501E",
      "firstName": "Gaio Giulio",
      "lastName": "Cesare",
      "birthDate": "1944-07-13",
      "birthDistrict": "RM",
      "birthCity": "Roma",
      "birthCountry": "IT",
      "sex": "M",
      "email": "a.mariano@teamsystem.com",
      "phoneNumber": "+393452495944"
    }
  }
}

## EVENTO DI COMPLETAMENTO CON ERRORE EMISSIONE CERTIFICATO
{
  "success": false,
  "traceId": "3d7425144d2e69e359f10755d8d7e997",
  "id": "651fca40d2cdf479208d7539",
  "context": "IDENTIFICATION_ENROLL",
  "event": "CERT_EMITTED",
  "data": {
    "intermediate": false,
    "code": "CTH_008",
    "detail": "Rao certificate pin invalid"
  }
}

Cancellazione sessione

E' possibile cancellare una sessione di identificazione e stacco chiamando il seguente metodo:

Cancellazione sessione

Ri-invio mail

E' possibile richiedere l'invio della mail di innesco della sessione chiamando il seguente metodo:

Ri-invio mail