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.

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

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

It creates the document, defines the participants* (signers) which in turn defines the kind of signature (digital, electronic or server signature), the document type, the signature format, the callback, etc. Sends a notification (email) including a link to the document that must be signed to the signers. The signers do not need to be registered in order 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.

  1. Select the Create resource;
  2. Inform your Token and Code;
  3. 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: signerselectronicSigners 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 = 28, that is a server certificate already configured and ready for use in Sandbox.

    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":"28"
                }
            ]
        }
                        
  4. Define the uploadId obtained in the previous step;
  5. Define the signers (signersand/orelectronicSigners and/or serverSigners);
  6. Click on Try it button
  7. Click on Send button
  8. The created document with signers info will be returned.

Performs the signature of a document by an external page which packs all the signature complexity. This page makes the signature process easier as it can be inserted into any system through an iframe, thus the security signature starts to be performed in the system itself, that is, it does not come out to an external system to perform the signature, and simplify integrating the digital signature systems.

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.

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.

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