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

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, codice fiscale dell'azienda.
fiscalCountry domicilio fiscale, se valorizzato viene fatto un controllo che il valore sia ISO 3166-1 alpha-2. Il valore di default da inserire è "IT", in caso 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 *1 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" *
}

Esempi FES

Esempi FEA

Esempi FEQ

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

*1 campo obbligatorio

Info

itemId *1 identificativo dell'azienda. Non può essere cambiato quindi deve avere lo stesso valore di quando il firmatario è stato creato
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

{
  "itemId": "string",
  "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"
}

V2 - ENROLLMENT

Start enrollment for a signer

[POST] /v2/rest/enrollment/start

Permette diinizializzare una sessione di enrollment per creare un certificato.

*1 campo obbligatorio

Info

signerId *1 identificativo del firmatario.
profile *1 può assumere questi determinati valori:
- "teamsystemTriennale"
- "teamsystemAuto"
- "teamsystemOneshot"
identificationProcesses array che definisce la modalità di riconoscimento, può avere dentro questi valori:
- "FEQ"
- "SPID"
owner *1 contiene le informazioni del firmatario.
owner.firstname*1.
owner.lastName*1.
owner.email*1.
owner.phoneNumber*1.
owner.fiscalCode
webhook *1 informazioni sul webhook da richiamare in fase di enrollment
webhook.url *1 url da richiamare deve essere l'URL della signer-write/v2/rest/enrollment/callback a cui va aggiunto come parametro di query:
- "signerId" *1 identificativo del firmatario

[
  {
    "signerId": "long",
    "profile": "string",
    "identificationProcesses": "string[]",
    "owner": {
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "phoneNumber": "string",
      "fiscalCode": "string"
    },
    "webhook": {
      "url": "string"
    }
  }
]

Response

[
  {
    "sessionId": "string"
  }
]

Delete existing enrollment session

[DELETE]/v2/rest/enrollment/session/{sessionId}

Permette di cancellare la sessione di enrollment

*1 campo obbligatorio

Info

sessionId identificativo della sessione di enrollment

Resend enrollment email

[PUT]/v2/rest/enrollment/session/{sessionId}/email/send

Permette di reinviare la mail di inizio enrollment

*1 campo obbligatorio

Info

sessionId identificativo della sessione di enrollment

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

Ricordarsi di inserire il mime type del formato, esempio: data:image/jpg;base64,/
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 permette di avere un adesione FEA cartacea, significa che viene scaricato sul cliente l'obbligo di conservare una copia cartacea dell'adesione FEA del firmatario. Se impostato a true permette di ricevere come response della chiamata il base64 del modulo di richiesta per la FEA e verrà attivata automaticamente senza firmare il modulo. se si vuole usare onlyUpload=true il valore deve essere impostato a false
onlyUpload se impostato a true permette di firmare l'adesione FEA insieme al caricamento del primo documento.
NOTA BENE, il primo documento che si caricherà per questo firmatario dovrà avere lo stesso mainSignerId e la stessa tipologia di firma e lo stesso strumento di autenticazione per essere valida. Inoltre fino a quando il firmatario non firmerà il primo documento non potrà sottoscriverne altri. Se invece viene impostato a false verra creata una sessione solo per la firma dell'adesione FEA.
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
}

Esempio

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

Migrate certificate

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

Permette di migrare un certificato da CA Trust a CA Teamsystem.

*1 campo obbligatorio

Info

certificateId *1 identificativo del certificato.
signerId *1 identificativo del firmatario.
profile *1 può assumere questi determinati valori:
- "teamsystemTriennale"
- "teamsystemAuto"
identificationProcesses array che definisce la modalità di riconoscimento, può avere dentro questi valori:
- "FEQ"
owner *1 contiene le informazioni del firmatario.
owner.firstname*1.
owner.lastName*1.
owner.email*1.
owner.phoneNumber*1.
owner.fiscalCode
webhook *1 informazioni sul webhook da richiamare in fase di enrollment
webhook.url *1 url da richiamare deve essere l'URL della signer-write/v2/rest/enrollment/callback a cui va aggiunto come parametro di query:
- "signerId" *1 identificativo del firmatario

{
  "signerId": "long",
  "profile": "string",
  "identificationProcesses": "string[]",
  "owner": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phoneNumber": "string",
    "fiscalCode": "string"
  },
  "webhook": {
    "url": "string"
  }
}