Invio della richiesta di creazione

La seguente documentazione fa riferimento alla versione 2 delle API di scrittura delle connessioni. La versione 1 è deprecata e non va utilizzata per nuove integrazioni.

In questo documento viene descritta l'API di creazione di una nuova connessione e gli eventuali errori che è possibile ricevere durante il processo..

API DI CREAZIONE

L'API di creazione di una nuova connessione è disponibile con metodo POST all'endpoint /api/v2/connections.

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Body

Il body della richiesta deve avere il seguente formato:

{
  "appId": "string",
  "featureCode": "string",
  "permission": "string",
  "recipientId": "string",
  "requesterId": "string",
  "serviceId": "string",
  "userRoles": [
    {
      "type": "TECH|PERSONAL",
      "userId": "string"
    }
  ]
}

• appId: identificativo dell'applicazione per la quale sta venendo effettuata la connessione (es: EIP)
• featureCode: identificativo della specifica feature dell'applicazione per la quale si sta effettuando la connessione. Se l'applicazione non ha feature secondarie, il campo va impostato a null. (es: SDI)
• permission: permessi da attribuire all'utente che sta creando la connessione. I valori accettati sono READ, READ_WRITE
• recipientId: identificativo univoco dell'item gestito all'interno dell'anagrafica di TSDigitial.
• requesterId: identificativo univoco dell'item gestore all'interno dell'anagrafica di TSDigitial.
• serviceId: identificativo univoco del servizio per il quale sta venendo effettuata la connessione. Ad ogni coppia appId + featureCode corrisponde uno ed un solo serviceId univoco. (es: SDI-FLOW)
• userRoles: array di utenze addizionali alle quali attribuire i ruoli risultanti dalla connessione. Se vuoto, i ruoli vengono assegnati alla sola utenza che ha effettuato la richiesta di connessione.
  • type: tipologia dell'utenza. TECH -> utenza applicativa, PERSONAL -> utenza regolare
  • userId: identificativo dell'utenza alla quale assegnare i ruoli (es: test@mondora.com, 12739bb6-9782-4d08-872e-98b8ea94e3ce)

L'elenco completo delle applicazioni presenti su TS Digital e dei relativi serviceId, appId, e featureCode è consultabile invocando l'apposita API del servizio services-subscription.

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 202. Ogni altro codice di risposta indica uno stato di errore.

HTTP 202

L'operazione è avvenuta con successo e il processo di creazione è stato preso in carico.

Body della risposta:

{}

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato. 

HTTP 409

L'azienda gestita ha già un gestore per il servizio specificato. Non è permesso creare più connessioni per uno stesso servizio.

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "status": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

• code: corrisponde al codice d'errore HTTP ritornato (es: 409)
• message: messaggio d'errore (es: Impossibile creare una connessione gia' esistente)
• status: descrizione a parole del codice d'errore HTTP (es: Conflict)
• subErrors: eventuali errori innestati in quello ritornato
• timestamp: data ed ora di ritorno dell'errore