Skip to main content

Signature Write

API di scrittura per Ts Digital Signature per le operazioni riguardanti i documenti. Swagger

Header

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

Il Content-Type deve essere application/json

Descrizione API

 

UPLOAD

Upload file for async sign

[POST] ​/v1​/rpc​/upload​/async

Permette di caricare un documento per il processo asincrono

Request body

  • transmitterId id dell'azienda
  • managerId id del commercialista dell'azienda
  • batchId
  • fileName nome del file da caricare
  • fileContent base64 del file da caricare. il limite è di 15MB
  • documentType tipo documento, consultare qui la lista dei tipi disponibili

  • owner dati relativi all'intestatario del documento, può essere una persona fisica o un azienda
  • owner.firstName
  • owner.lastName
  • owner.companyName ragione sociale
  • owner.vat partita iva
  • owner.fiscalCode codice fiscale
  • owner.kind tipo dell'intestatario. i valori possibili sono company o person

  • metadata dati aggiuntivi per la conservazione del documento. Chiedere info in più perchè ogni tipo di documento ha dei metadati di conservazione diversi
  • autoSendCCT permette di mandare automaticamente il documento in conservazione una volta che il documento è stato firmato, per far si che la conservazione avvenga serve che l'azienda abbia il servizio di cct attivo e abbia inserito tutti i metadata obbligatori per lo specifico documento
  • signatureMode  i valori che può assumere sono pades o cades
  • mainSignerId identificativo deldi un firmatario che ilha un certificato di FeqFEQ automatica che servirà per sigillare il documento. //TODO 
  • expiryDate data di scadenza del documento //TODO
  • year anno di riferimento del documento
  • signatureProcessName //TODOtipo di processo di firma. I valori possono essere:
    • FEA remota
    FEA grafometrica FES remota FEA remota FEQ remota areSignersOrdered //TODO


    attachments eventuali allegati del documento, gli allegati qui verrano solo specificati mentre il caricamento verrà effettuato durante il processo di firma della sessione attachments.description: descrizione dell'allegato attachments.signerFiscalCode: codice fiscale del firmatario a cui richiedere l'allegato (deve essere presente tra i firmatari)  

    attachments.details: array dei file che verranno richiesti nella sessione di firma. Indipendentemente dal numero di attachments.details specificati il risultato finale sarà un PDF con l'aggregazione dei details di un singolo allegato. attachments.details.description: descrizione del file da caricare attachments.details.optional: impostare a true se non si vuol rendere l'allegato obbligatorio


    signers array di firmatari che devono firmare il documento signers.fiscalCode signers.firstName signers.lastName signers.email email del firmatario signers.mobile numero del telefono cellulare del firmatario, verrà utilizzato per la sessione di firma signers.canEmailBeSentAgain //TODO DA ELIMINARE

    signers.signatureData array delle area di firma del firmatario sul documento signers.signatureData.signatureType identifica il tipo di firma che verrà effettuata, tutte le area di firma sul documento devono avere lo stesso valore. I tipi disponibili sono:
      SecureCall tipologia disponibile per FEA remota e FES remota otp tipologia disponibile per FEA remota e FES remota BioSignature tipologia che serve per la FEA grafometrica fes_noservice tipologia che serve per la FES grafometrica FSM tipologia che serve per la FEQ remota signers.signatureData.fieldGroup può essere valorizzato con un valore personalizzato, se lo stesso fieldGroup verrà messo su più aree di firma il firmatario le firmerà contemporaneamente sennò verrà richiesta una firma per ogni singola aree di firma presente sul documento signers.signatureData.shortDescription descrizione corta dell'area sul documento Limite caratteri //TODO signers.signatureData.longDescription descrizione lunga dell'area sul documento. Limite caratteri //TODO signers.signatureData.textType signers.signatureData.positioningStrategy signers.signatureData.optional impostare a true se non si vuol rendere l'area di firma obbligatoria signers.signatureData.textType identifica il tipo di area sul documento, se non impostato di default verrà messo come area di firma. I tipi possono essere:  
        signature area di firma checkbox per inserire una checkbox //TODO
        radiobutton per inserire un radio button //TODO
        text per inserire del testo //TODO signers.signatureData.positioningStrategy



        multipleDocumentSession se impostato a true il documento farà parte di una sessione multi documento (più documenti verrano firmati con un unica sessione di firma) useSignatureTimestamp permette di applicare una marca temporale al documento sendSignedDocumentToMail se impostato a true i firmatari presenti nel documento alla fine della firma del documento riceveranno una mail con in allegato il documento firmato  
          {
  "transmitterId": "string",
  "managerId": "string",
  "batchId": "string",
  "fileName": "string",
  "fileContent": "string",
  "documentType": "string",
  "owner": {
    "firstName": "string",
    "lastName": "string",
    "companyName": "string",
    "vat": "string",
    "fiscalCode": "string",
    "kind": "string"
  },
  "metadata": {
    "cct": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "document": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "autoSendCCT": true,
  "signatureMode": "string",
  "mainSignerId": "string",
  "expiryDate": "string",
  "year": 0,
  "signatureProcessName": "string",
  "areSignersOrdered": true,
  "attachments": [
    {
      "description": "string",
      "signerFiscalCode": "string",
      "details": [
        {
          "description": "string",
          "optional": true
        }
      ]
    }
  ],
  "signers": [
    {
      "fiscalCode": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "mobile": "string",
      "canEmailBeSentAgain": true,
      "signatureData": [
        {
          "signatureType": "string",
          "fieldGroup": "string",
          "shortDescription": "string",
          "longDescription": "string",
          "textType": "string",
          "positioningStrategy": "string",
          "coordsRegion": {
            "page": 0,
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "fieldNameRegion": {
            "name": "string",
            "offsetX": 0,
            "offsetY": 0,
            "w": 0,
            "h": 0
          },
          "textPatternRegion": {
            "pattern": "string",
            "number": 0,
            "offsetX": 0,
            "offsetY": 0,
            "w": 0,
            "h": 0
          },
          "optional": true
        }
      ]
    }
  ],
  "commonSign": true,
  "multipleDocumentSession": true,
  "useSignatureTimestamp": true,
  "sendSignedDocumentToMail": true
}

          Upload file and download signed document

          [POST] ​/v1​/rpc​/upload​/sync

          Desc

          Append document to multiDocumentSession

           

          Desc

          JOB

          Start signature job

          [POST] ​/v1​/jobs​/start

          Permette di creare la sessione di firma del processo asincrono per firmare il documento

          Request body

          • hubId identificativo del documento
          • sendMail default = true, permette di ricevere una mail con il link per la sessione di firma per ogni firmatario

          Start signature job for multiDocuments

          [POST] ​/v1​/jobs​/start​/multidocument

          Permette di creare la sessione di firma del processo asincrono contemporaneamente su più documenti(documenti multi sessione) 

          Request body

          • multiDocumentSessionId id del documento multi sessione
          • sendMail default = true, permette di ricevere una mail con il link per la sessione di firma per ogni firmatario

          Cancel signature job

          [POST] ​/v1​/jobs​/cancel

          //TODO

          CCT

          Send document to cct

          [POST] ​/v1​/cct​/send

          Permette di inviare un documento in conservazione

          Request body

          • hubId identificativo del documento

          Send documents to cct

          [POST] ​/v1​/cct​/send​/multi

          Permette di inviare più documenti in conservazione per un massimo di 50 documenti per chiamata

          Request body

          • hubIds array di hubId
          MAIL

          Resend signature mail

          [POST] ​/v1​/mail​/resend

          Permette di rimandare la mail con il link per la sessione di firma per uno o più firmatari di un documento se non hanno ancora firmato

          Request body

          • hubId identificativo del documento
          • fiscalCodes array dei codici fiscali dei firmatari presenti all'interno del documento che devono ricevere di nuovo la mail
          DOCUMENT

          Archive a document

          [POST] ​/v1​/document​/{hubId}​/archive

          Permette di eliminare un documento. Il documento verrà spostato in una collection quindi per la ricerca eventuale del documento eliminato bisogna utilizzare l'api apposta

          Path params

          • hubId identificativo del documento

          Archive a multiDocument session

          [POST] ​/v1​/document​/multiDocumentSession​/{multiDocumentSessionId}​/archive

          Permette di eliminare un documento multi sessione. Il documento verrà spostato in una collection quindi per la ricerca eventuale del documento eliminato bisogna utilizzare l'api apposta

          Path params

          • multiDocumentSessionId id del documento multi sessione

          Unarchive a document

          [POST] ​/v1​/document​/{hubId}​/unarchive

          Permette di ripristinare un documento eliminato. Solamente i documenti in stato Firmato o Caricato possono essere ripristinati

          Path params

          • hubId identificativo del documento

          Unarchive a multiDocument session

          [POST] ​/v1​/document​/multiDocumentSession​/{multiDocumentSessionId}​/unarchive

          Permette di ripristinare un documento multi sessione eliminato. Solamente i documenti in stato Firmato o Caricato possono essere ripristinati

          Path params

          • multiDocumentSessionId id del documento multi sessione

          Remove from multiDocument session

          [PATCH] ​/v1​/document​/{hubId}​/removeFromMultiDocumentSession

          Permette di eliminare un documento da una sessione multi documento. Il documento nello specifico non verrà cancellato ma verrà considerato con un normale singolo documento //TODO

          Path params

          • hubId identificativo del documento
          TEMPLATE

          Titolo

           

          Desc

          Titolo

           

          Desc

          Titolo

           

          Desc

          Titolo

           

          Desc

          Titolo

           

          Desc

          Titolo

           

          Desc

           

           
           
           
           
           
           
           

           

              "attachments": [
        {
            "description": "carta d'identita'",
            "signerFiscalCode": "BNDNRC85M29G284G",
            "details": [
                {
                    "description": "fronte",
                    "optional": false
                },
                {
                    "description": "retro",
                    "optional": false
                }
            ]
        },
        {
            "description": "foto segnaletica",
            "signerFiscalCode": "MNNRFL96D21I829W",
            "details": [
                {
                    "description": "foto",
                    "optional": false
                }
            ]
        }
    ],

           


          Upload Async Multi Doc
          POST /v1/rpc/upload/async/multiUpload

          Permette il caricamento di più documenti che poi verrano firmati in un unica sessione di firma. I documenti dovranno avere in comune

            • stessa modalità di firma

            • stessa modalità di autenticazione

            • stessa applicabilità della marca temporale

            • stesso mainSignerId
            • stesso transmitterId

          Con il parametro autoStartIdSignSession settato a true, l'api manderà alla firma tutti i documenti in un unica sessione appena il caricamento di tutti i file su storage è avvenuto.

          Come body della request va passato un array di documenti

          [
    {
        "transmitterId": "MNNRFL96D21I829W",
        "mainSignerId": "MNNRFL96D21I829W",
        "expiryDate": "30/04/2020",
        "year": "2020",
        "fileName": "sample1.pdf",
        "fileContent": "base64",
        "documentType": "0000",
        "signatureProcessName": "FEA remota",
        "owner": {
            "fiscalCode": "MNNRFL96D21I829W",
            "companyName": "Azienda1",
            "kind": "company"
        },
        "signatureMode": "pades",
        "autoSendCCT": false,
        "signers": [
            {
                "firstName": "Raffaele",
                "lastName": "Mainini",
                "email": "rmainini@mondora.com",
                "mobile": "",
                "fiscalCode": "MNNRFL96D21I829W",
                "signatureData": [
                    {
                        "shortDescription": "Firma1",
                        "longDescription": "1",
                        "signatureType": "otp", //tutti i documenti devono avere la stessa signatureType
                        "optional": false,
                        "positioningStrategy": "coords",
                        "fieldGroup": "fieldGroup",
                        "coordsRegion": {
                            "page": 1,
                            "h": 0.05,
                            "w": 0.25,
                            "x": "0.03",
                            "y": "0.03"
                        }
                    }
                ]
            }
        ],
        "metadata": {},
        "areSignersOrdered": false
    },
    {
        "transmitterId": "MNNRFL96D21I829W",
        "mainSignerId": "MNNRFL96D21I829W",
        "expiryDate": "30/04/2020",
        "year": "2020",
        "fileName": "sample2.pdf",
  		"fileContent": "base64",
        "documentType": "0000",
        "signatureProcessName": "FEA remota",
        "owner": {
            "fiscalCode": "MNNRFL96D21I829W",
            "companyName": "Azienda2",
            "kind": "company"
        },
        "signatureMode": "pades",
        "autoSendCCT": false,
        "signers": [
            {
                "firstName": "Raffaele",
                "lastName": "Mainini",
                "email": "rmainini@mondora.com",
                "mobile": "",
                "fiscalCode": "MNNRFL96D21I829W",
                "signatureData": [
                    {
                        "shortDescription": "Firma1",
                        "longDescription": "1",
                        "signatureType": "otp",
                        "optional": false,
                        "positioningStrategy": "coords",
                        "fieldGroup": "fieldGroup",
                        "coordsRegion": {
                            "page": 1,
                            "h": 0.05,
                            "w": 0.25,
                            "x": "0.03",
                            "y": "0.03"
                        }
                    }
                ]
            }
        ],
        "metadata": {},
        "areSignersOrdered": false
    },  {
        "transmitterId": "MNNRFL96D21I829W",
        "mainSignerId": "MNNRFL96D21I829W",
        "expiryDate": "30/04/2020",
        "year": "2020",
        "fileName": "sample3.pdf",
 		"fileContent": "base64",   
        "documentType": "0000",
        "signatureProcessName": "FEA remota",
        "owner": {
            "fiscalCode": "MNNRFL96D21I829W",
            "companyName": "Azienda3",
            "kind": "company"
        },
        "signatureMode": "pades",
        "autoSendCCT": false,
        "signers": [
            {
                "firstName": "Raffaele",
                "lastName": "Mainini",
                "email": "rmainini@mondora.com",
                "mobile": "",
                "fiscalCode": "MNNRFL96D21I829W",
                "signatureData": [
                    {
                        "shortDescription": "Firma1",
                        "longDescription": "1",
                        "signatureType": "otp",
                        "optional": false,
                        "positioningStrategy": "coords",
                        "fieldGroup": "fieldGroup",
                        "coordsRegion": {
                            "page": 1,
                            "h": 0.05,
                            "w": 0.25,
                            "x": "0.03",
                            "y": "0.03"
                        }
                    }
                ]
            }
        ],
        "metadata": {},
        "areSignersOrdered": false
    }
  
]

          Response

          {
    "hubIds": [
        "5ea1b3c73460de1e28b5f05a",
        "5ea1b3c83460de1e28b5f05b",
        "5ea1b3c83460de1e28b5f05c",
        "5ea1b3c83460de1e28b5f05d",
        "5ea1b3c83460de1e28b5f05e",
        "5ea1b3c83460de1e28b5f05f",
        "5ea1b3c93460de1e28b5f060",
        "5ea1b3c93460de1e28b5f061"
    ],
    "batchId": "bb6ecb06-3796-4193-b813-25f8efceb6bb", // il batchId servirà in fase di lettura per recuperare tutti documenti di una sessione
    "url": "https://appdev.teamsystemdigital.com/portale/#/MNNRFL96D21I829W/apps/firma/list/batchId/bb6ecb06-3796-4193-b813-25f8efceb6bb",
    "errors": null,
    "documentsInError": 0,
    "documentsCreated": 0
}

          Upload Sync
          POST /v1/rpc/upload/sync

          Permette il caricamento di un file da firmare seguendo il processo sincrono

           

          Start Jobs
          POST /v1/jobs/start

          Permette di mandare alla firma un documento. 

          {
    "hubId": "5e9711e301be5d000720fc05",
    "sendEmail": true //può non esssere messo visto che ti default è sempre true, per ora l'invio avviene solamente tramite mail
}

          In caso di più documenti caricati tramite l'api /v1/rpc/upload/async/multiUpload dovrà essere settato il queryParams multiSession=true e dovrà essere passato come body un hubId di quelli ricevuti nella risposta dell'upload.

          Esempio 

          //RESPONSE MULTI UPLOAD
{
    "hubIds": [
        "5ea1b3c73460de1e28b5f05a",
        "5ea1b3c83460de1e28b5f05b",
        "5ea1b3c83460de1e28b5f05c", //HUBID PER LA CHIAMATA
    ],
    "batchId": "bb6ecb06-3796-4193-b813-25f8efceb6bb",
    "url": "https://appdev.teamsystemdigital.com/portale/#/MNNRFL96D21I829W/apps/firma/list/batchId/bb6ecb06-3796-4193-b813-25f8efceb6bb",
    "errors": null,
    "documentsInError": 0,
    "documentsCreated": 0
}
          // BODY REQUEST START JOB
{
    "hubId": "5ea1b3c83460de1e28b5f05c",
}

           


          Cancel Jobs
          POST /v1/jobs/cancel

          Permette di cancellare un job precedentemente avviato. Questo comporta l'eliminazione o lo stralcio del documento. Lo stato del documento passerà in ELIMINATO se tutto il processo di firma non era ancora concluso altrimenti in STRALCIATO. I documenti già mandati in CCT non possono essere ne eliminati ne stralciati.

           

          Back to top