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:

{
  "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.

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.

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:

{
  "success": true,
  "traceId": "c03b592fe3a3d05e6a60f1fcd809f0b7",
  "id": "651fb390d2cdf479208d7533",
  "context": "IDENTIFICATION_ENROLL",
  "event": "SESSION_OPENED",
  "data": {
    "intermediate": true
  }
}
{
  "success": false,
  "traceId": "999ea355bf8d1ab275e4808b56b3d0c5",
  "id": "651fb390d2cdf479208d7533",
  "context": "IDENTIFICATION_ENROLL",
  "event": "IDENTIFICATION",
  "data": {
    "intermediate": false,
    "code": "IDN_008",
    "detail": "External provider identification failed"
  }
}

{
  "success": true,
  "traceId": "86f72deb36ab999dd31806598cc05a16",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "IDENTIFICATION",
  "data": {
    "intermediate": true
  }
}

{
  "success": true,
  "traceId": "4be434fa8b3599d21d8259e4af7c6e63",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "USER_SUBMITTED_DATA",
  "data": {
    "intermediate": true
  }
}

{
  "success": true,
  "traceId": "3f9da6511cc1c56284907c409e74a2a0",
  "id": "651fbc33d2cdf479208d7538",
  "context": "IDENTIFICATION_ENROLL",
  "event": "CERT_OPENED",
  "data": {
    "intermediate": true
  }
}

{
  "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"
    }
  }
}

Back to top