Tutorials
Tutorials
Prerequisite
Before starting testing with the Certillion API, some prerequisites are necessary:
- Obtain access credentials
- Have a valid ICP-Brasil certificate to test your integration or request a test certificate
- Install the Certillion app if the certificate is type A1 (file) or physical media A3 (card or token)
The credentials can be obtained in the Contact, requesting a test account. When requesting a test account, you must send the following information:
- Company Name
- Visible name of the company (which will appear on the authentication screen for the user)
- CNPJ
- Technical Contact: name, email, telephone
System Authentication
To be able to call the Certillion API methods, you must first authenticate the system that will make the requests. With the credentials provided (see Prerequisites), authenticate using the method:
| Step | Description |
| 1: /client_token | Call for authentication using credentials. |
List of Supported Cloud Certificates
Certillion supports all cloud certificate providers in ICP-Brasil (PSC – Trust Service Providers). The Certillion server provides and automatically updates the complete list of PSC identifiers.
| Step | Description |
| 1: access the login page via digital certificate | Access the page using your PSC. |
| 2: Request the login page | Make the authentication request. |
| 3: /psc-info | Call that searches for all PSCs compatible with Certillion. |
The developer can use this list to generate the interface for their user, so that they can easily identify and use digital certificates through Certillion.
Location of Certificates
Using the API, it is also possible to locate the certificates that the user has in the cloud, based on the legal identifier that you want to search for.
| Step | Description |
| 1: enter CPF or CNPJ | Legal identifier required to search for the PSC. |
| 2: request list of PSCs | Request for PSCs using the legal identifier. |
| 3: /find-psc-accounts | Call that finds PSC accounts using a legal identifier. |
Note: This method will return a list whose entries are the result of the search in each of the PSCs. Each entry in this list will contain the PSC identifier and a status indicating whether the user has a certificate (status=”Y”). If all entries have the status=”N”, the only option offered to the user is to sign using the Certillion app with local certificates, A1 in a file or A3 on physical media (card or token).
User Authentication (Signatory)
Before signing any document, the user must authorize access to their digital certificate.
| Step | Description |
| 1: select the PSC | Selects your PSC. |
| 2: Forwards the chosen PSC | Sends the selected PSC. |
| 3: /authorize (returns authentication page) | Authorization call for the PSC to identify the signer and Certillion. |
| 4: Displays authentication page | Application displays authentication page authentication. |
| 5: provides authentication data | Signatory provides credentials. |
| 6: /token | Call to obtain the security code (token). |
You can grant authorization in three ways:
- single_signature: User grants authorization for the system to execute ONE request for signing ONE document.
- multiple_signature: User grants authorization for the system to execute ONE request for a batch of documents (ONE or more).
- signature_session: User grants authorization for the system to execute, for a specific period of time, as many requests as desired. Each request can be for a batch of one or more files.
Signing Documents
Follow the steps outlined in the diagram below to sign the document.
| Step | Description |
| 1: Click sign | Signer selects option to sign. |
| 2: Request signature | Calls the method that requests the document signature. |
| 3: /document (POST) | Call that uploads the document to be signed. |
| 4: /signature | Call that signs the document. |
| 5: /document (GET) | Call that downloads the signed document. |
To sign a document by multiple people, you do a single initial upload, followed by requesting signatures from each person sequentially. You do not need to repeat all the steps three times; simply request the signature from each signer.
Important! Correct Error Handling
If any of the 3 methods used above for signing fails, repeat ONLY the call to that method:
- if the 2nd method /signature fails, call only this method, it is NOT necessary to upload the file again
- if the 3rd method /document (get) fails, just make another call to download the signed document, it is NOT necessary to upload it again or request a new signature
Repeating requests that were processed correctly may generate additional charges for the system that requests the signatures.
Signature Verification
Certillion verifies any ICP-Brasil digital signature, even if an external system made the signature. To do this, use the /verify call.
| Step | Description |
| 1: /document (POST) | Uploads the document to be signed. |
| 2: /verify | Call that verifies any digital signature ICP-Brasil. |
To check the possible return codes from Certillion, consult the Online API in the method Status Codes returned by calls to Certillion
Confidentially and Performace Optimization
As seen in the signing process, you must send the document to the servers Certillion for it to be signed or verified. After signing, the document must also be signed. At Certillion, we guarantee the confidentiality of documents through the following practices:
- no processing is performed beyond what is necessary for the processing of the digital signature;
- no information contained in the documents is extracted or analyzed, even anonymously;
- the document is stored in encrypted form on the servers;
- the document remains on the servers for at least 24 hours and a maximum of 48 hours so that it can be downloaded after signing, after which it is irreversibly deleted.
Despite this, when using the Certillion cloud server, some applicants may prefer, however, not to have to send documents to a third-party service. Through the Certillion Agent component, it is possible for the document to be pre-processed in the applicant’s environment, avoiding the need for uploading. Similarly, after completing the signature, the system generates the signed document locally. This approach has the following advantages:
- Compliance with possible company regulations of not externalizing documents with confidential or private information;
- Signing is faster because it is not necessary to transmit the documents in both directions.
- No need to change the integration code, the Certillion Agent is a network-neutral component.
After completing the integration of your system, request the installation of the Certillion Agent version in your environment.
| Step | Description |
| 1: /document (POST) | Call that uploads the document to be signed on the signer’s local server. |
| 2: hash calculation | Summary of the document that was sent. |
| 3: /signature | Call: that performs the signing of the document on the signatory’s local server. |
| 4: /signature | Call that performs the signing of the document on the Certillion server. |
| 5: / document (GET) | Call that downloads the signed document from the signatory’s local server. |
| 6: generates signed document | Application requests the signed document from the signatory’s local server. |
Certillion Signer
Cloud-based digital certificates eliminate the need for any application in the user environment that will sign the documents. The PSC environment, duly accredited for this purpose, processes digital certificates securely. When the user has traditional digital certificates (A1 in a file and A3 on a card or token), it is a serious security breach to ask them to provide the certificate to your system.
This can invalidate the signature and generate legal liability for the person who received it. To protect the system that requests the signature made with traditional certificates, the user must be asked to use the Certillion local signer. This application ensures that you generate the signature securely and in compliance with the standards. If you developed your system with the Certillion API, you do not need to change the integration code, as it is already compatible with the signer! Other great advantages of the Certillion signer:
- No plugins are required for it to work in web systems;
- It works on the main platforms: Windows, Mac, Android, iPhone, iPad and Linux;
- It has no additional cost, and is even free to download;
| Step | Description |
| 1: select the chosen PSC | Select your PSC. |
| 2: forward the PSC chosen | Send the PSC selected. |
| 3: /authorize (returns authentication page) | Authorization call to PSC to identify signer and Certillion. |
| 4: displays authentication page | Application displays authentication page. |
| 5: provides authentication data | Signer provides credentials. |
| 6: /token | Call to get the security code (token). |