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 del firmatario che il certificato di Feq automatica che servirà per sigillare il documento. //TODO 
  • expiryDate data di scadenza del documento //TODO
  • year anno di riferimento del documento
  • signatureProcessName //TODO
  • 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
  • signers.signatureData.fieldGroup
  • signers.signatureData.shortDescription
  • signers.signatureData.longDescription
  • signers.signatureData.textType
  • signers.signatureData.positioningStrategy
  • signers.signatureData.optional impostare a true se non si vuol rendere l'area di firma obbligatoria



  • 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