How the APIs Work

The Certisign Portal integration API allows you to add digital and electronic signature to systems through its Internet-available resources using the WebAPIs (Rest) technology. The available resources allow you collect signatures for a particular document, automatically sign a large quantity of documents using server signature, notifying the signers by email, following the signature process and downloading the signed documents.

Digital Signature: signature performed by using digital certificate in hardware (token or card) - A3 , software - A1 ou mobile - A2;
Electronic Signature: Signature performed by graphism (handwritten) and other signature evidences captured;
Server Signature: Automatic signature performed by server using digital certificate located on our HSM.

Basic Flow

This walkthrough shows how to performe a basic signature flow, from uploading the file to downloading the signed document, as well as of the tools available at Developer Portal:

API Console: provides a simple interface to test the APIs with request samples for resources;
Signature Sample: allows you sign your test documents showing the embedded signature working;

To perform this walkthrough you must have already followed the Getting Started steps.

1. Upload

Uploads the document (file) to be signed to a temporary repository on the server to be distributed to the signers.

Uploading a sample file to sign using the Upload API.

Select Upload feature;
Select your Subscription key;
Click on Try it button
Click on Send button
Copy the uploadId from the response for use in the next step.

2. Send for Signature

It creates the document, defines the participants* (signers) which in turn defines the kind of signature (digital, electronic or server signature), document type, signature format, etc. Sends to the signers an email notification with a link to sign. This option can be disabled directly in the Certisign Portal administration site page. The signers do not need to be registered to sign.

* Participant is all Taxpayer Registration (In Brazil is CPF) that is part of the signature flow.

Sending the uploaded document in the previous step for signature using the API Create.

Select the Create resource;
Inform your Token;
Click on the model field to upload the request sample on DOCUMENT field;
The simplified request below might be used instead of the full example provided in the API Browser, which has unnecessary fields on a simple test. Copy this request, change the uploadId for the obtained in step 1, inform the sender data and configure the signers lists.
The signers lists: signers, electronicSigners and serverSigners can be used together or individualy, omitting or sending null for those won't be need. It's also possible defines an order to the signatures using the field step. If an order does not necessary, just send 1 to all the step fields. The order is defined by signature, i.e., among signers in the same signers list or beteween the differents signers lists, for example: first of all one signer of the signers list sign the document. Next, one signer of the electronicSigners list, and after, one more signer of the signers list sign the document. Last of all, one signer of the serverSigners sign.

signers: Signers list wich will sign the document using digital certificate;
electronicSigners: Signers list wich will sign the document in the electronic way, doing the graphism (handwritten);
serverSigners: Server signers list wich will sign the documentlist. This signature is done automatically when the document is submited. To use this option, use certificateID = 72, that is a server certificate already configured and ready for use in Sandbox;
Sender: Should be used if you want to include the person is sending the document. Could be omitted if you want to say only that the company is sending.

PS 1: Sender may be the signer himself, i.e., sending a document to the own signature.
PS 2: The CPF should be informed in the individualIdentificationCode..
```
                            
    { 
        "document":{  
            "name":"PDF-Exemplo.pdf",
            "upload":{  
                "id":"uploads/13750-6d3cb347-6ed9-4851-ab37-d858a802aa83/PDF-Exemplo.pdf",
                "name":"PDF-Exemplo.pdf"
            }
        },
        "sender":{  
            "name":"João da Silva",
            "email":"joao@mail.com",
            "individualIdentificationCode":"30762573902"
        },
        "signers":[  
            {  
                "step":1,
                "title":"Signer",
                "name":"Maria Aparecida",
                "email":"maria.aparecida@gmail.com",
                "individualIdentificationCode":"62591035886"
            }
        ],
        "electronicSigners":[  
            {  
                "step":2,
                "title":"Signer",
                "name":"José de Souza",
                "email":"jose.souza@gmail.com",
                "individualIdentificationCode":"21082796956"
            }
        ],
        "serverSigners":[  
            {  
                "step":3",
                "certificateId":"72"
            }
        ]
    }
                    
```
Define the uploadId obtained in the previous step;
Define the signers (signers and/or electronicSigners and/or serverSigners);
Click on Try it button
Click on Send button
The created document with signers info will be returned.

3. Sign

Performs the signature of a document from an external page that packs the entire complex process of signing. It's makes easier to embed in any system a digital e/ou electronic signature using our JavaScript API.

Digital Signature

The signature in this page is carried out by a Chrome plugin that interfaces with the user's machine to list your certificate(s) and request your PIN. As stated above, this page encapsulates all the complexity of the signature, such as the use of this plugin and the entire connection with the Portal de Assinaturas APIs in order to simplify the digital signature process in integration. If you have not installed this plugin yet, you are redirected to the installation page. You do not need to have an administrator user to install it. As it can be observed in the image below, the external page has basic formatting, therefore it does not conflict with the layouts of the systems in which it will be inserted.

The View button is an option to ensure that the document is displayed before being signed. This option can be set directly in the Certisign Portal administration site page.

Signing the document sent in the previous step using the Signature Samples tool.

4. Download

Download a signed or partially signed document, if it has not yet been completed (all signers have not yet signed).

When a document is using CAdES format for signature, the download is a package (.zip) that contains the original document (optional), a manifest in PDF and .p7s signature file that is the type attached. If used PAdES format (for signing PDF only), the actual PDF document is returned signed.

See more about signature formats.

Package

Performs the download of the document or signature package (zip).

Downloading the document signed in the previous step using the Package API.

Select Package resource;
Click on Try it button
Define Key field with the value obtained in the previous step;
IncludeOriginal, defines whether the original file will also be returned;
IncludeManifest, defines whether the manifest file will also be returned;
Zipped, defines whether package will be returned as a zip file or json;
Click on Send button
The Siganture Package will be returned.