Signer Write

API di scrittura per Ts Digital Signature per le operazioni riguardanti i firmatari e i certificati. Swagger

Header

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

Il Content-Type deve essere application/json

NB: Utilizzate le API V2, le v1 sono deprecate e verranno eliminate nel 31/12/2021.

In tutte le chiamate dove è richiesto ServiceName non impostare nulla a meno che si vuole utilizzare le api per il servizio adempimenti.

Descrizione API

V2 - SIGNER

Create a new signer

[POST] /v2/rest/signer

Permette la creazione di un firmatario per una determinata azienda

*1 campo obbligatorio
*2 campo obbligatorio in caso si voglia richiedere un certificato di FEQ automatica o di FEQ remota

Info

firstName *1, nome.
lastName *1, cognome.
fiscalCode *1, in caso si tratti di un firmatario italiano(dispone di codice fiscale, solamente questi firmatari possono richiedere un certificato di FEQ automatica o di FEQ remota). In caso il firmatario non abbia un codice fiscale il campo non deve essere compilato perchè verrà generato un UUID come id del firmatario. In caso di firmatario italiano viene fatto un controllo sulla lunghezza di 16 caratteri.
itemId *1, identificativo dell'azienda.
fiscalCountry domicilio fiscale se valorizzato viene fatto un controllo che il valore sia ISO 3166-1 alpha-2. Se il firmatario è sprovvisto di codice fiscale il valore non può essere "IT".
sex *1, viene fatto un controllo che il valore sia "M" o "F".
birthCity città di nascita.
birthDate *1, data di nascita.
birthCountry se valorizzato viene fatto un controllo che il valore sia ISO 3166-1 alpha-2.
birthDistrict provincia di nascita, in caso di nascita all'estero il valore da passare è "EE". In caso di provincia italiana si deve usare la sigla da 2 cifre.
city città di residenza.
country nazione di residenza, se valorizzato viene fatto un controllo che il valore sia ISO 3166-1 alpha-2.
district -> campo non usato, verrà dismesso.
cap cap di residenza, se valorizzato viene fatto un controllo che il valore sia di 5 caratteri e che contenga solo numeri.
address indirizzo di residenza.
email *1 indirizzo email.
prefixCellNumber prefisso numero di telefono, se non valorizzato il valore di default sarà "+39", per richiedere una FEQ automatica o di FEQ remota il prefisso non può essere diverso da "+39". //TODO
cellNumber *1, numero di telefono personale, solo numeri.
documentIssuer *2, ente che ha rilasciato il documento.
documentNumber *2, numero del documento.
documentEndDate *2, data di scadenza del documento.
documentType *2, può assumere questi determinati valori:
- "Carta d'identità"
- "Patente di guida"
- "Passaporto"
- "Porto d'armi"
- "Tessera di riconoscimento postale"
- "Tessera rilasciata da PA"

ownerTaxId codice fiscale dell'azienda su cui il firmatario e stato assegnato .
ownerVatNumber partita iva dell'azienda su cui il firmatario e stato assegnato .
ownerDescription ragione sociale dell'azienda su cui il firmatario e stato assegnato .
serviceName controllare le info su questo campo in cima al documento.

{
  "firstName": "string", *
  "lastName": "string", *
  "fiscalCode": "string", *
  "itemId": "string", * 
  "fiscalCountry": "string", *
  "sex": "string", *
  "birthCity": "string", *
  "birthCountry": "string",*
  "birthDate": "2021-02-12T14:53:00.676Z", *
  "birthDistrict": "string",
  "city": "string",
  "country": "string",
  "district": "string",
  "cap": "string",
  "address": "string",
  "email": "string", *
  "documentIssuer": "string",
  "documentNumber": "string",
  "documentEndDate": "2021-02-12T14:53:00.676Z",
  "documentType": "string",
  "cellNumber": "string", *
  "ownerTaxId": "string",
  "ownerVatNumber": "string",
  "ownerDescription": "string",
  "serviceName": "A-FISCALI-IVA-FLOW" *
}

Response

{
  "signerId": 0,
  "itemId": "string",
  "fiscalCode": "string"
}

Disable an existent signer and disable all certificates

[DELETE] /v2/rest/signer/{signerId}

Permette di eliminare un determinato firmatario. Oltre a cancellare il firmatario verranno eliminate le extraSignature(FES/FEA) e i certificati collegati al firmatario(FRM/FSM). La cancellazione è solamente logica, verrà impostato enabled=false. In caso si provi a ricreare il firmatario con lo stesso codice fiscale verrà chiamata in automatico l'API Update an existent signer, il firmatario verrà riattivato e in caso aggiornate le properties

Info

signerId identificativo del firmatario
serviceName controllare le info su questo campo in cima al documento

Update an existent signer

[PATCH]/v2/rest/signer/{signerId}

Permette di aggiornare i dati di un firmatario

Info

city città di residenza.
country nazione di residenza, se valorizzato viene fatto un controllo che il valore sia ISO 3166-1 alpha-2.
district -> campo non usato, verrà dismesso.
cap cap di residenza, se valorizzato viene fatto un controllo che il valore sia di 5 caratteri e che contenga solo numeri.
address indirizzo di residenza.
email indirizzo email.
prefixCellNumber prefisso numero di telefono, se non valorizzato il valore di default sarà "+39", per richiedere una FEQ automatica o di FEQ remota il prefisso non può essere diverso da "+39". //TODO
cellNumber numero di telefono personale, solo numeri.
documentIssuer ente che ha rilasciato il documento
documentNumber numero del documento
documentEndDate data di scadenza del documento
documentType può assumere questi determinati valori:
- "Carta d'identità"
- "Patente di guida"
- "Passaporto"
- "Porto d'armi"
- "Tessera di riconoscimento postale"
- "Tessera rilasciata da PA"
ownerTaxId codice fiscale dell'azienda su cui il firmatario e stato assegnato
ownerVatNumber partita iva dell'azienda su cui il firmatario e stato assegnato
ownerDescription ragione sociale dell'azienda su cui il firmatario e stato assegnato
serviceName controllare le info su questo campo in cima al documento

{
  "city": "string",
  "district": "string",
  "cap": "string",
  "address": "string",
  "email": "string",
  "documentIssuer": "string",
  "documentNumber": "string",
  "documentEndDate": "2021-02-12T15:30:23.713Z",
  "documentType": "string",
  "cellNumber": "string",
  "ownerTaxId": "string",
  "ownerVatNumber": "string",
  "ownerDescription": "string",
  "serviceName": "A-FISCALI-IVA-FLOW"
}

V2 - EXTRA SIGNATURE

Activate FES

[POST] /v2/rest/extraSignature/fes/{signerId}

Permette di attivare la tipologia la FES (firma elettronica semplice) ad un determinato firmatario.

Info

signerId identificativo del firmatario

Initialize FEA

[POST] /v2/rest/extraSignature/fea

Permette di effettuare l'adesione FEA (firma elettronica avanzata) per un determinato firmatario. Il processo di attivazione sarà completato solamente una volta firmato il documento che verrà in automatico generato e mandato in firma

Info

signerId identificativo del firmatario
transmitterId identificativo dell'azienda
imagesContent base64 delle immagini o pdf del documento del firmatario e del codice fiscale. Da inserire se non sono ancora stati conservati le copie di questi documenti. I file dei documenti possono essere .pdf., .jpg, .jpeg, .jpe, .png, .tiff, .tif
documentSignType metodo con cui verrà firmato il documento. I valori possibili possono essere FEA remota o FEA grafometrica
mainSignerId codice fiscale del firmatario possessore di un certificato di Firma elettronica qualificata automatica(FRM) che sigillerà il documento
useOtp valore da mettere a true solamente se documentSignType è FEA remota. Questo permetterà di utilizzare come strumento di autenticazione del modulo di richiesta per la FEA tramite otp e non SecureCall
paperSignature questo valore permette di ricevere come response della chiamata il base64 del modulo di richiesta per la FEA e verrà attivata automaticamente senza firmare il modulo
itemData dati riguardanti all'azienda a cui fa capo il firmatario
itemData.id
itemData.vatNumber
itemData.city
itemData.fullAddress
itemData.description
itemData.address
itemData.itemCellNumber
itemData.itemEmail
itemData.policyNumber
itemData.webSite

{
  "transmitterId": "string",
  "imagesContent": [
    "string"
  ],
  "signerId": 0,
  "documentSignType": "string",
  "mainSignerId": "string",
  "itemData": {
    "id": "string",
    "vatNumber": "string",
    "city": "string",
    "fullAddress": "string",
    "description": "string",
    "address": "string",
    "itemCellNumber": "string",
    "itemEmail": "string",
    "policyNumber": "string",
    "webSite": "string"
  },
  "useOtp": true,
  "paperSignature": true
}

Delete Extra Signature

[DELETE] /v2/rest/extraSignature/{extraSignatureId}

Permette di eliminare le extraSignature (FEA, FES) di un determinato firmatario.

Info

signerId identificativo del firmatario
extraSignatureId identificativo della FES o FEA collegate ad un firmatario

V2 - CERTIFICATE

Un assign certificate to signer

[POST] /v2/rest/certificate/{certificateId}/unAssignTo/{signerId}

Sostituisce le API v1 /v1/rest/certificate/frm/unassign-certificate e /v1/rest/certificate/fsm/unassign-certificate

Scollega un certificato da un firmatario

Info

signerId identificativo del firmatario
certificateId identificativo del certificato
serviceName controllare le info su questo campo in cima al documento

Send submit request to Trust to start certificate validation

[POST] /v2/rest/certificate/{certificateId}/send

Sostituisce le API v1 /v1/rest/certificate/fsm/ca/submit e /v1/rest/certificate/frm/ca/submit

Permette di finalizzare le richieste dei certificati di Firma elettronica qualificata remota/Firma elettronica qualificata automatica(FSM/FRM) mandate alla CA

Info

signerId identificativo del firmatario
certificateId identificativo del certificato che viene staccato durante la richiesta di inizializzazione
file base64 del file pdf di richiesta pre compilato e firmato pades
serviceName controllare le info su questo campo in cima al documento

{
  "signerId": 0,
  "certificateId": 0,
  "file": "string",
  "serviceName": "SIGNATURE-FLOW"
}

Assign certificate to signer

[POST] /v2/rest/certificate/{certificateId}/assignTo/{signerId}

Sostituisce le API v1 /v1/rest/certificate/frm/assign-certificate e /v1/rest/certificate/fsm/assign-certificate

Permette di assegnare ad un firmatario un certificato già creato in precedenza da un altra azienda.

Nome	Cognome	Codice fiscale	ItemId	CertificateId
Utente1	Utente1	CF1	ITEM1	CERT1
Utente1	Utente1	CF1	ITEM2

l'api si occupa di collegare il certificato se il firmatario è lo stesso ma per diverse aziende

Nome	Cognome	Codice fiscale	ItemId	CertificateId
Utente1	Utente1	CF1	ITEM1	CERT1
Utente1	Utente1	CF1	ITEM2	CERT1

Info

signerId identificativo del firmatario
certificateId identificativo del certificato
serviceName controllare le info su questo campo in cima al documento
itemId identificativo dell'azienda
name ragione sociale dell'azienda

{
  "itemId": "string",
  "name": "string"
}

Initialize an remote Feq

[POST] /v2/rest/certificate/fsm

Sostituisce API v1 /v1/rest/certificate/fsm/initialize

Permette di inizializzare la richiesta per il certificato FSM (Firma elettronica qualificata remota) che poi sarà mandata alla CA.

Info

signerId identificativo del firmatario
itemId identificativo dell'azienda
identificationType permette di specificare lo strumento di autenticazione che verrà utilizzato per il certificato di FEQ qualificata remota. I valori accettati sono otp o SecureCall. Se il parametro non viene specificato di default viene utilizzato SecureCall
serviceName controllare le info su questo campo in cima al documento

{
  "signerId": 0,
  "serviceName": "SIGNATURE-FLOW",
  "itemId": "string",
  "identificationType": "string"
}

Initialize an automatic Feq

[POST] /v2/rest/certificate/frm

Sostituisce API v1 /v1/rest/certificate/frm/initialize

Permette di inizializzare la richiesta per il certificato FRM (Firma elettronica qualificata automatica) che poi sarà mandata alla CA.

Info

signerId identificativo del firmatario
itemId identificativo dell'azienda
pin valore di 8 cifre numeriche che serviranno come pin del certificato
serviceName controllare le info su questo campo in cima al documento

{
  "signerId": 0,
  "serviceName": "SIGNATURE-FLOW", 
  "itemId": "string",
  "pin": "string"
}