VídeoTutorial

Material de Apoio: Como Usar a API Certillion

1. Credenciales de acceso

Para acceder a la plataforma Certillion, necesita las credenciales a continuación. Para saber cómo obtener credenciales, visite la sección tutoriales.

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

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

2. Colección del Postman

Accede a la Colección Postman en la parte inferior de esta página. Utiliza las variables de entorno CLIENT_ID y CLIENT_SECRET.

Puede:

1. 1. Reemplace las variables directamente con los valores dados.
   2. O bien configure las variables en el entorno Postman.

3. Flujo de firma digital con OAuth2

El flujo de firma básico con Certillion es el siguiente:

1. 1. oauth/client_token
   2. oauth/document (subir documento)
   3. oauth/authorize
   4. oauth/token
   5. oauth/signature
   6. oauth/document (download) (opcional, solo si se carga)

Extra:

El endpoint oauth/find-psc-accounts se puede utilizar para averiguar qué PSC un CPF o CNPJ tiene un certificado digital disponible.

4. Generación de desafío de código y verificador de código (PKCE)

En las llamadas a /authorize y /token, necesitará un code_challenge y un code_verifier.

Ejemplo de generación en 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);

Consejo:

Puede ejecutar este código en línea haciendo clic aquí

5. Ejecutar /authorize

En Postman, complete los campos obligatorios y copie la URL generada.

Abra esta URL en su navegador. Serás redirigido al PSC (por ejemplo, VIDAAS) para la autenticación.

Después de autenticarse, será redirigido a una URL similar a: «https://esec.com.br/callback?code=a9ef7f76-1118-4731-95b5-4ead66ec9457&state=123»

6. Configuraciones importantes

En el campo redirect_uri de las solicitudes /authorize y /token, utilice la URL base hasta /callback, por ejemplo: «https://esec.com.br/callback»

El parámetro de código obtenido de la URL se utilizará en la llamada oauth/token.

7. PSC y endpoints

El campo psc debe configurarse de acuerdo con el PSC que se utilizará.

Para los certificados A1 o A3 conectados a la máquina del usuario final, utilice: CERTILLION_SIGNER

Puntos finales:

1. 1. Para CERTILLION_SIGNER: «https://cloud-ws.certillion.com»
   2. Para otros PSC: «https://cloud.certillion.com»

8. Documentación oficial

La documentación completa de la API está disponible en certillion.com/es/api

9. Firmas separadas de CAdES (hash de archivo)

Para las firmas CAdES independientes, es necesario calcular el hash sha256 del archivo y pasarlo en el campo hash de la solicitud.

Ejemplo en bash:

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

Explicación del comando:

sha256sum.exe e-Sec_com_linha.jpg: genera el hash sha256 del archivo.

awk '{ print $1}': captura solo el valor hexadecimal del hash.

xxd -r -p: convierte hash hexadecimal a binario.

base64: transforma el hash binario en base64.

El resultado en base64 será el valor que se utilizará en el campo hash de la solicitud de firma.