Integración basada en comprobaciones

Crea flujos de KYC y verificación de identidad basados en comprobaciones con el SDK web de ComplyCube.

Descripción general

Esta guía te guía a través de la integración del Web SDK con ComplyCube usando el enfoque basado en checks, dándote control directo sobre cada paso de verificación.

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

Estás viendo la basado en comprobaciones guía del SDK: un enfoque que ofrece un control detallado, pero es más adecuado para socios o casos de uso avanzados. Recomendamos usar integración del flujo de trabajo para la mayoría de las implementaciones.

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 del SDK

Tu backend debe crear un token del 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 del SDK para obtener más información.

Importar el SDK

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

<!DOCTYPE html>
<html>
  <head>
    ...
    <!-- Importando la biblioteca 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 para desarrolladores.

Montar el SDK

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

ComplyCube.mount({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'complycube-mount',
  stages: [
    'intro',
    'documentCapture',
    {
      name: 'faceCapture',
      options: {
        mode: 'video'
      }
    },
    'completion'
  ],
  onComplete: function(data) {
    // Usando los atributos de datos devueltos, solicita a tu
    // servidor backend que realice los checks necesarios de ComplyCube
    console.info('Captura completada');
  },
  onModalClose: function() {
    // Gestiona el intento de cierre del modal
  },
  onError: function ({ type, message }) {
    if (type === 'token_expired') {
      // Solicita un nuevo token del SDK
    } else {
      // Gestiona otros errores
      console.error(message);
    }
  }
});

Los parámetros de montaje del SDK se describen en la sección de configuración del SDK a continuación.

Política de referrer

Para permitir una comunicación correcta entre el SDK y nuestros servidores, el encabezado de la política de referrer de tu página web debe configurarse como 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 checks

Usando los datos devueltos por el SDK, a través de la callback onComplete ahora puedes indicar a tu servidor backend que ejecute los checks apropiados usando el endpoint para crear un check.

Por ejemplo, usa:

documentCapture.documentId para ejecutar un check de documento.
documentCapture.documentId y faceCapture.livePhotoId para ejecutar un check de identidad.
documentCapture.documentId y faceCapture.liveVideoId para ejecutar un check de identidad mejorado.
poaCapture.documentId para ejecutar un check de prueba de domicilio.

Si has configurado webhooks como se describe en nuestra guía de webhooks, se te notificará una vez que un check se complete.

Para recuperar los resultados del check, puedes realizar una solicitud GET de check.

Ejemplo de solicitud

curl -X GET https://api.complycube.com/v1/checks/{:checkId} \\
     -H 'Authorization: <YOUR_API_KEY>'

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

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

const check = await complycube.check.get("CHECK_ID");

using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var check = await checkApi.GetAsync("CHECK_ID");

Referencia del SDK

Esta sección describe todos los ajustes configurables, callbacks, métodos del ciclo de vida y opciones de marca disponibles en el Web SDK de ComplyCube.

Configuración

Opción

Descripción

token

El token del SDK generado por tu backend. Esto es obligatorio. Tipo: string

containerId

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

Tipo: string Valor predeterminado: complycube-mount

useModal

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

useFullScreen

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

disableClientAnalytics

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

Tipo: boolean Valor predeterminado: false

stages

Esta es la lista de etapas por las que pasarán tus clientes. Las etapas pueden proporcionarse como cadenas o como objetos. Consulta Etapas a continuación para obtener más información.

Tipo: array[object] o array[string]

Valores predeterminados: ['intro', 'faceCapture, 'documentCapture', 'completion']

language

El idioma de la interfaz. Los valores válidos incluyen:

en , ar, br, de, es, fr, hi, hk, id, it, ja, ko, nl, no, pl, pt, sv, th, vi, zh

Tipo: string Valor predeterminado: en

Devolución de llamada

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

Opción

Descripción

callback onComplete

Se activa después de que el cliente completa el flujo de verificación. Normalmente se usa para desencadenar un check en tu backend.

Según las etapas proporcionadas, datos puede incluir los siguientes atributos:

documentCapture
- documentId: ID del documento capturado.
- documentType: Tipo del documento cargado.
faceCapture
- liveVideoId: ID del video capturado. O;
- livePhotoId: ID de la foto capturada.
poaCapture
- documentId: ID del documento de comprobante de domicilio cargado.
- documentType: Tipo del documento de comprobante de domicilio cargado.

onError

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

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

onExit

Esta devolución de llamada se activa cuando el 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 atributo isModalOpen usando updateSettings.

Actualización de 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()

Etapas

La stages array define el flujo de verificación. Cada etapa puede pasarse como un string o como un objeto con opciones.

Nombres de etapas compatibles

intro: Pantalla de bienvenida.
userConsentCapture: Capturar el consentimiento del cliente.
documentCapture: Capturar documentos de identificación.
faceCapture: Capturar selfies o videos de prueba de vida.
poaCapture: Capturar documento de comprobante de domicilio.
completion: Fin del flujo.

Cuando userConsentCapture está habilitado, gestiona siempre el onExit callback si el cliente rechaza el consentimiento.

Asegúrate de pasar el clientConsent parámetro cuando tu cliente otorgue el consentimiento.

Cuando una etapa se pasa como objeto, tendrá dos atributos, name y options.

Nombre

Este es el nombre de la etapa

Opciones

Esto te permite personalizar cada etapa de la siguiente manera:

Nombre de la etapa

Opciones

intro

heading: Cambia el encabezado de la pantalla de introducción.
message: Una lista de mensajes para mostrar en la pantalla de introducción. Tamaño máximo 3.
startButtonText: Cambia el texto del botón de inicio en la pantalla de introducción.

documentCapture

crossDeviceOnly: Un booleano que indica si se debe obligar a los usuarios a capturar su documento usando su teléfono. Esto elimina la opción de carga de documentos.
documentTypes: La lista de tipos de documentos de identificación visibles para el usuario. Los tipos de documento válidos incluyen:
- passport
- driving_license
- national_identity_card
- residence_permit
Cada valor puede ser ya sea un boolean o un objeto de país. Un booleano alterna la visibilidad del tipo de documento, mientras que un objeto de país especifica el país emisor para documentos que no sean pasaporte, omitiendo la pantalla de selección de país. El valor del país es el código ISO de país de dos letras.

faceCapture

mode: El modo de la captura facial. Los valores posibles son: photo o video.

poaCapture

documentTypes: La lista de tipos de documentos de Comprobante de Domicilio (POA) visibles para el cliente. Los tipos de documento POA válidos incluyen:
- bank_statement
- utility_bill

El valor de cada tipo de documento es un booleano que alterna la visibilidad del tipo de documento.

completion

heading: Cambia el encabezado de la pantalla de finalización.
message: Un mensaje para mostrar en la pantalla de finalización. Tamaño máximo 1.

Objeto de opciones de ejemplo

stages: [
  {
    name: "intro",
    options: {
      heading: "Necesitamos verificar tu identidad",
      message: [
        "Para abrir una cuenta, necesitamos comprobar algunas cosas.",
        "Esto solo tomará un momento",
      ],
      startButtonText: "Iniciar verificación"
    },
  },
  "userConsentCapture",
  {
    name: "documentCapture",
    options: {
      crossDeviceOnly: true,
      documentTypes: {
        passport: true,
        driving_license: false,
        national_identity_card: true,
        residence_permit: {
          country: "GB",
        },
      },
    },
  },
  {
    name: "faceCapture",
    options: {
      mode: "video"
    },
  },
  {
    name: "poaCapture",
    options: {
      documentTypes: {
        bank_statement: true,
        utility_bill: false,
      },
    },
  },
  {
    name: "completion",
    options: {
      heading: "Gracias por completar el proceso",
      message: ["nos pondremos en contacto contigo en breve"]
    },
  }
];

Identidad de marca

Puedes personalizar la apariencia y el estilo del SDK con el branding objeto. Se compone de los atributos que se indican a continuación.

Apariencia

La apariencia el objeto le permite personalizar el esquema de colores del SDK con valores CSS (p. ej., RGBA, Hex). Los atributos personalizables incluyen:

Atributo

Descripción

infoPopupColor

Color de fondo del popup de advertencia.

infoPopupTextColor

Color de fondo del popup de advertencia.

infoPopupLinkHoverColor

Color de fondo al pasar el cursor del enlace alternativo del popup de advertencia.

infoPopupLinkActiveColor

Color de fondo activo del enlace alternativo del popup de advertencia.

errorPopupColor

Color de fondo del popup de error.

errorPopupTextColor

Color del texto del popup de error.

errorPopupLinkHoverColor

Color de fondo al pasar el cursor del enlace alternativo del popup de error.

errorPopupLinkActiveColor

Color de fondo activo del enlace alternativo del popup de error.

cameraButtonHoverColor

Color de fondo del botón de la cámara al pasar el cursor.

cameraButtonActiveColor

Color de fondo activo del botón de la cámara.

iconButtonActiveColor

Color de fondo activo del botón de icono.

iconButtonHoverColor

Color de fondo del botón de icono al pasar el cursor.

primaryButtonColor

Color de fondo del botón principal.

primaryButtonTextColor

Color del texto del botón principal.

primaryButtonActiveColor

Color de fondo activo del botón principal.

primaryButtonHoverColor

Color de fondo del botón principal al pasar el cursor.

primaryButtonBorderColor

Color del borde del botón principal.

secondaryButtonColor

Color de fondo del botón secundario.

secondaryButtonTextColor

Color del texto del botón secundario.

secondaryButtonActiveColor

Color de fondo activo del botón secundario.

secondaryButtonHoverColor

Color de fondo del botón secundario al pasar el cursor.

secondaryButtonBorderColor

Color del borde del botón secundario.

documentSelectorColor

Color de fondo del selector de documentos.

documentSelectorTextColor

Color del texto del selector de documentos.

documentSelectorActiveBorderColor

Color de fondo activo del selector de documentos.

documentSelectorHoverBorderColor

Color de fondo del selector de documentos al pasar el cursor.

linkHoverColor

Color de fondo del enlace al pasar el cursor.

linkActiveColor

Color de fondo activo del enlace.

linkUnderlineColor

Color del subrayado del enlace.

linkHoverTextColor

Color del texto del enlace al pasar el cursor.

bodyTextColor

Color del texto del contenido del SDK.

headingTextColor

Color del texto de los encabezados del SDK.

subheadingTextColor

Color del texto de los subencabezados del SDK.

Logotipo

La logo el objeto tiene los siguientes atributos:

lightLogoUrl: URL de la versión clara de tu logotipo.
darkLogoUrl: URL de la versión oscura de tu logotipo.

Ejemplo de marca del logotipo

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  logo: {
    lightLogoUrl: 'light_logo_url',
    darkLogoUrl: 'dark_logo_url',
  }
},

Marca de texto

La textBrand el atributo representa el formato textual de tu marca.

Ejemplo de marca textual

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  textBrand: 'Acme Bank'
}

Si logo y textBrand los atributos se especifican al mismo tiempo, logo tiene prioridad.