Integración de workflows

Integra flujos de trabajo de KYC en tu aplicación web usando el SDK web de ComplyCube.

Descripción general

Esta guía te muestra cómo integrar el Web SDK con ComplyCube flujos de trabajo.

Para un ejemplo rápido de copiar y pegar, usa nuestro asistente de integración.

Flujo de integración

El SDK web se ejecuta como parte de tu frontend, pero depende de tu backend para crear tokens seguros. Así es como funciona:

Crear un cliente

Registrar un nuevo cliente (es decir, cliente) usando la API de ComplyCube

Genera un token del SDK

Tu backend solicita un token JWT vinculado a ese cliente.

Importa y monta el SDK

Añade los archivos JS y CSS, luego monta el SDK en tu aplicación web.

Captura documentos, vídeos y selfies

El SDK guía a tu cliente a través de los pasos requeridos.

Realizar comprobaciones de verificación

Los datos capturados se envían de forma segura a ComplyCube para las comprobaciones de verificación, y los resultados se entregan en tiempo real a través de la API o de webhooks.

Guía de integración

Crear un cliente

Cada flujo de verificación comienza con un cliente (es decir, cliente). Usa la API para crear el cliente.

Ejemplo de solicitud

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "john.doe@example.com",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const client = await complycube.client.create({
  type: "person",
  email: "john.doe@example.com",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'john.doe@example.com',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

client = cc_api.clients.create(**new_client)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => 'john@doe.com',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));
var newClient = new ClientRequest {
  type = "person",
  email = "john@doe.com",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newClient);

Ejemplo de respuesta

La respuesta contendrá un id (el ID del cliente). Es necesario para el siguiente paso.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "john.doe@example.com",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

Consulta Referencia de la API de clientes para obtener más información.

Genera un token de SDK

Tu backend debe crear un token de SDK para cada nuevo flujo. Este token vincula la sesión del SDK con el cliente. Los tokens tienen una vida útil corta y no deben reutilizarse.

Ejemplo de solicitud

curl -X POST https://api.complycube.com/v1/tokens \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "referrer": "https://www.example.com/*"
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const token = await complycube.token.generate("CLIENT_ID", {
    referrer: "https://www.example.com/*"
});

using ComplyCube.Net;
using ComplyCube.Net.Resources.SDKTokens;

var sdkTokenApi = new SDKTokenApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var sdkTokenRequest = {
  clientId = "CLIENT_ID",
  referrer = "https://www.example.com/*"
}

var sdkToken = await sdkTokenApi.GenerateToken(sdkTokenRequest);

Ejemplo de respuesta

{
    "token": "<CLIENT_TOKEN>"
}

Consulta Referencia de la API de tokens de SDK para obtener más información.

Importa el SDK

Para importar nuestro Web SDK, debes incluirlo en el HTML de la página de destino:

<!DOCTYPE html>
<html>
  <head>
    ...
    <!-- Importando la biblioteca de JavaScript -->
    <script src="complycube.min.js"></script>

    <!-- Importando el CSS predeterminado -->
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
     <!-- Aquí es donde se montará el Web SDK -->
    <div id="complycube-mount"></div>
  </body>
</html>

Cargando el SDK con integridad (Opcional)

Para mayor seguridad, puedes cargar opcionalmente el ComplyCube Web SDK usando Subresource Integrity (SRI). Esto permite al navegador verificar que los archivos JavaScript y CSS no hayan sido modificados validándolos frente a sumas de comprobación criptográficas.

Recupera los últimos valores de integridad del SDK

Para asegurarte de usar siempre la última versión compatible del SDK y los hashes de integridad más recientes, recupera los metadatos del recurso desde el endpoint de información del Web SDK.

Ejemplo de solicitud

curl -X POST https://api.complycube.com/v1/webSdk/latest \\
     -H 'Authorization: <YOUR_API_KEY>'

Ejemplo de respuesta

La respuesta incluye las URL y los valores de integridad correspondientes tanto para los recursos de JavaScript como para los de CSS.

{
  "js": {
    "url": "<JAVASCRIPT_ASSET_URL>/complycube.min.js",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  },
  "css": {
    "url": "<CSS_ASSET_URL>/style.css",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  }
}

Importa el SDK usando atributos de integridad

Usa los valores devueltos para cargar el SDK en tu HTML con integridad y crossorigin atributos:

<!DOCTYPE html>
<html>
  ...
  <head>
    <!-- Importando la biblioteca JavaScript -->
    <script
      src="<JAVASCRIPT_ASSET_URL>/sdk.min.js"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
    </script>

    <!-- Importando el CSS predeterminado -->
    <link
      rel="stylesheet"
      href="<CSS_ASSET_URL>/style.css"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
  </link>
  </head>
  
  <!-- Aquí es donde se montará el Web SDK -->
  <body>
    <div id="complycube-mount"></div>
  </body>
</html>

Notas

Usar SRI es opcional, pero se recomienda para entornos con requisitos de seguridad más estrictos.
El atributo crossorigin="anonymous" es necesario cuando se usa SRI con recursos servidos desde un origen diferente.
Los valores de integridad pueden cambiar cuando el SDK se actualiza. Recupera siempre los valores más recientes desde el endpoint.

Los enlaces a complycube.min.js y style.css se pueden encontrar en tu portal de desarrolladores.

Montar el SDK

Como parte del montaje del Web SDK, debes especificar un ID de plantilla de flujo de trabajo. El SDK ejecutará automáticamente la activa versión del flujo de trabajo seleccionado.

Una vez completado el flujo de verificación, los clientes son redirigidos de vuelta a la URL de retorno que especifiques.

Con el token generado, el Web SDK se puede inicializar en tu frontend usando el siguiente código JavaScript:

ComplyCube.mount({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'complycube-mount',
  workflowTemplateId: "WORKFLOW_TEMPLATE_ID",
  onComplete: function(data) {    
    // Haz que tu backend notifique a ComplyCube una vez que el flujo de trabajo haya finalizado
    // para activar las comprobaciones de verificación
    console.info('Capture complete');
  },
  onModalClose: function() {
    // Gestiona el intento de cierre del modal
  },
  onError: function ({ type, message }) {
    if (type === 'token_expired') {
      // Solicita un nuevo token de SDK
    } else {
      // Gestiona otros errores
      console.error(message);
    }
  }
});

Los parámetros de montaje del SDK se describen en la Configuración del SDK sección siguiente.

Política de referrer

Para habilitar una comunicación correcta entre el SDK y nuestros servidores, la Política de referrer cabecera debe establecerse en strict-origin-when-cross-origin. Esto garantiza que la información del referrer se transmita de forma segura durante las solicitudes HTTP.

Puedes hacerlo programáticamente o añadirlo directamente a la página web de la siguiente manera: <meta name="referrer" content="strict-origin-when-cross-origin">

Realizar comprobaciones de verificación

Una vez que tu cliente inicie el flujo, una sesión de flujo de trabajo se crea automáticamente. Esta sesión contiene todos los datos capturados (documentos, imágenes y videos), así como el seguimiento del progreso. Puedes verlos todos a través de la página de sesiones de flujo de trabajo en el portal o a través de la API.

Cuando el flujo termina, el SDK activa la onComplete función de devolución de llamada. La devolución de llamada proporciona un data objeto que incluye el workflowSessionId. Tu backend debe usar este ID para notificar a ComplyCube que el flujo de trabajo ha finalizado, lo que a su vez ejecuta las comprobaciones de verificación definidas en el flujo de trabajo.

Si has configurado webhooks como se describe en nuestra guía de webhooks, recibirás una notificación cuando se complete una sesión de flujo de trabajo.

Puedes recuperar los detalles de una sesión de flujo de trabajo llamando a la solicitud para recuperar la sesión de flujo de trabajo.

Ejemplo de una solicitud completa de sesión de flujo de trabajo

curl -X POST https://api.complycube.com/v1/workflowSessions/{:wfSessionId}/complete \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const wfSession = await complycube.workflowSession.complete("WORKFLOW_SESSION_ID");

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

workflow_session = cc_api.workflowsessions.complete('WORKFLOW_SESSION_ID')

using ComplyCube.Net;
using ComplyCube.Net.Resources.WorkflowSessions;

var wfSessionApi = new WorkflowSessionApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var workflowSession = await wfSessionApi.CompleteAsync("WORKFLOW_SESSION_ID");

Referencia del SDK

En esta sección se describen todos los ajustes configurables, callbacks, métodos del ciclo de vida y opciones de personalización de marca disponibles en el Web SDK de ComplyCube.

Configuración

Opción

Descripción

token

El token de SDK generado por tu backend. Esto es obligatorio. Tipo: cadena

workflowTemplateId

El ID de la plantilla de flujo de trabajo que se cargará para esta sesión. Esto es obligatorio.

Tipo: cadena

containerId

El ID del elemento contenedor donde se monta el SDK. Debe ser un elemento vacío.

Tipo: cadena Valor predeterminado: complycube-mount

useModal

Esto define si las pantallas de la interfaz se cargan en un modal en lugar de integradas en línea. Tipo: booleano Valor predeterminado: verdadero

useFullScreen

Esto define si el SDK se carga en modo de pantalla completa. Tipo: booleano Valor predeterminado: falso

disableClientAnalytics

Esto define si rastreamos o no la analítica del cliente.

Tipo: booleano Valor predeterminado: falso

Callback

Los callbacks te permiten responder a los eventos del ciclo de vida del SDK.

Opción

Descripción

onComplete

Se activa después de que el cliente complete el flujo de verificación. Se utiliza para invocar una solicitud de finalización de sesión de flujo de trabajo.

onError

Se activa cuando ocurre un error. El objeto de error tiene dos atributos:

type: Puede ser:
- excepción
- token_expired : indica que el token ha expirado. Cuando esto ocurra, se debe proporcionar un nuevo token de SDK.
message: Descripción del error.

onExit

Esta callback se activa cuando tu cliente sale antes de completar el flujo. Devolverá el motivo de salida, por ejemplo, USER_CONSENT_NOT_GRANTED.

onModalClose

Se activa cuando el cliente intenta cerrar el modal. Puedes permitir o impedir el cierre actualizando el isModalOpen atributo usando updateSettings.

Actualizando la configuración

Varios ajustes pueden actualizarse en tiempo de ejecución de la siguiente manera:

complycube = ComplyCube.mount({...});

// Reemplazar el token del SDK
complycube.updateSettings({ token: "NEW_SDK_TOKEN" });
...
// Abrir el modal
complycube.updateSettings({ isModalOpen: true });

//Cerrar el modal
complycube.updateSettings({ isModalOpen: false });

Desmontando el SDK

Si está utilizando el SDK en una aplicación de una sola página (SPA), puede llamar a la función unmount para eliminar el SDK y restablecer su estado.

complycube = ComplyCube.mount({...});
...
complycube.unmount()

Identidad de marca

Puedes personalizar los colores, los logotipos y otros elementos de marca a través de la página de configuración de la marca, si está disponible en tu plan.