VídeoTutorial

Support Material: How to Use the Certillion API

1. Access Credentials

To access the Certillion platform, you need the credentials below. To learn how to obtain the credentials, visit the tutorials.

"client_id": ".....",

"client_secret": "......"

2. Postman Collection

Access the Postman Collection at the bottom of this page. It uses the environment variables CLIENT_ID and CLIENT_SECRET.

You can:

1. 1. Replace variables directly with the given values.
   2. Or set the variables in the Postman environment.

3. Digital Signature Flow with OAuth2

The basic signing flow using Certillion is as follows:

1. 1. oauth/client_token
   2. oauth/document (document upload)
   3. oauth/authorize
   4. oauth/token
   5. oauth/signature
   6. oauth/document (download) (optional, only if uploaded)

Extra:

The oauth/find-psc-accounts endpoint can be used to find out which PSCs a CPF or CNPJ has a digital certificate available.

4. Generating Code Challenge and Code Verifier (PKCE)

In the calls to /authorize and /token, you will need a code_challenge and a code_verifier.

Example of generation in Node.js:

var crypto = require('crypto')
function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));
console.log("verifier: " + verifier);
function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));
console.log("challenge: " + challenge);

Tip:

You can run this code online by clicking here

5. Running /authorize

In Postman, fill in the required fields and copy the generated URL.

Open this URL in your browser. You will be redirected to the PSC (e.g. VIDAAS) for authentication.

After authenticating, you will be redirected to a URL similar to: “https://esec.com.br/callback?code=a9ef7f76-1118-4731-95b5-4ead66ec9457&state=123”

6. Important Settings

In the redirect_uri field of the /authorize and /token requests, use the base URL up to /callback, for example: “https://esec.com.br/callback”

The code parameter obtained from the URL will be used in the oauth/token call.

7. PSC and Endpoints

The psc field must be configured according to the PSC that will be used.

For A1 or A3 certificates connected to the end user machine, use: CERTILLION_SIGNER

Endpoints:

1. 1. For CERTILLION_SIGNER: “https://cloud-ws.certillion.com”
   2. For other PSCs: “https://cloud.certillion.com”

8. Official Documentation

Full API documentation is available at certillion.com/en/api

9. CAdES Detached Signatures (File Hash)

For detached CAdES signatures, it is necessary to calculate the sha256 hash of the file and pass it in the hash field of the request.

Example in bash:

$ sha256sum.exe e-Sec_com_linha.jpg | awk '{ print $1}' | xxd -r -p | base64

Command explanation:

sha256sum.exe e-Sec_com_linha.jpg: generates the sha256 hash of the file.

awk '{ print $1}': captures only the hexadecimal value of the hash.

xxd -r -p: convert hexadecimal hash to binary.

base64: transforms the binary hash into base64.

The result in base64 will be the value to be used in the hash field of the signature request.