Videotutorial

Material de Apoio: Como Usar a API Certillion

1. Credenciais de Acesso

Para acessar a plataforma Certillion, você precisa das credenciais abaixo. Para saber como obter as credenciais, acesse a seção de tutoriais.

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

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

2. Collection do Postman

Acesse a Collection do Postman no final desta página. Ela utiliza as variáveis de ambiente CLIENT_ID e CLIENT_SECRET.

Você pode:

1. 1. Substituir as variáveis diretamente pelos valores fornecidos.
   2. Ou definir as variáveis no ambiente do Postman.

3. Fluxo de Assinatura Digital com OAuth2

O fluxo básico de assinatura usando o Certillion é o seguinte:

1. 1. oauth/client_token
   2. oauth/document (upload do documento)
   3. oauth/authorize
   4. oauth/token
   5. oauth/signature
   6. oauth/document (download) (opcional, apenas se houver upload)

Extra:

O endpoint oauth/find-psc-accounts pode ser usado para descobrir quais PSCs um CPF ou CNPJ possuem certificado digital disponível.

4. Gerando Code Challenge e Code Verifier (PKCE)

Nas chamadas para /authorize e /token, você precisará de um code_challenge e um code_verifier.

Exemplo de geração em 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);

Dica:

Você pode executar esse código online clicando aqui 

5. Executando o /authorize

No Postman, preencha os campos necessários e copie a URL gerada.

Abra essa URL no navegador. Você será direcionado para o PSC (ex.: VIDAAS) para autenticação.

Após autenticar, você será redirecionado para uma URL parecida com: “https://esec.com.br/callback?code=a9ef7f76-1118-4731-95b5-4ead66ec9457&state=123”

6. Configurações Importantes

No campo redirect_uri das requisições /authorize e /token, use a URL base até o /callback, exemplo: “https://esec.com.br/callback”

O parâmetro code obtido na URL será usado na chamada oauth/token.

7. PSC e Endpoints

O campo psc deve ser configurado conforme o PSC que será utilizado.

Para certificados A1 ou A3 conectados na máquina do usuário final, utilize: CERTILLION_SIGNER

Endpoints:

1. 1. Para CERTILLION_SIGNER: “https://cloud-ws.certillion.com”
   2. Para outros PSCs: “https://cloud.certillion.com”

8. Documentação Oficial

A documentação completa da API está disponível em certillion.com/api

9. Assinaturas CAdES Detached (Hash do Arquivo)

Para assinaturas CAdES detached, é necessário calcular o hash sha256 do arquivo e passá-lo no campo hash da requisição.

Exemplo em bash:

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

Explicação do comando:

sha256sum.exe e-Sec_com_linha.jpg: gera o hash sha256 do arquivo.

awk '{ print $1}': captura apenas o valor hexadecimal do hash.

xxd -r -p: converte o hash hexadecimal para binário.

base64: transforma o hash binário em base64.

O resultado em base64 será o valor a ser utilizado no campo hash da requisição de assinatura.