API de Validación Biométrica Facial - Biometric Circuit API

El API de Validación Biométrica Facial o Biometric Circuit API permite iniciar y gestionar un proceso de firma electrónica con validación biométrica (videofirma), automatizando la creación y seguimiento de circuitos de firma en entornos regulados y no regulados.

Esta API ha sido diseñada para integrarse fácilmente en los sistemas de clientes corporativos, permitiendo una experiencia de firma segura, auditable y completamente digital.

Vea también el artículo sobre personalización de la experiencia web del circuito

Objetivo del API de Validación Biométrica Facial

El objetivo de este servicio es brindar un mecanismo de integración API-first para:

Iniciar circuitos de videofirma.

Cargar documentos para firma biométrica.

Obtener enlaces para el proceso de firma.

Recuperar documentos firmados una vez completado el circuito.

Requisitos Previos

Antes de comenzar con la implementación de esta API, asegúrate de tener:

Credenciales válidas, incluyendo:

client_id
client_secret

Identificador del canal o id de la experiencia web channel que debe ser provisto por su Account Manager asignado de DANAconnect. Vea también el artículo sobre personalización de la experiencia web del circuito

Acceso al subdominio personalizado provisto por su Account Manager asignado de DANAconnect.

Configuración adecuada de permisos y ambiente desde el lado del cliente para manejar llamadas HTTPS.

Conocimientos básicos de JSON, ya que tanto las solicitudes como las respuestas de la API están estructuradas en este formato.

Autenticación

Deberás obtener un token de acceso antes de invocar cualquier endpoint principal.

Endpoint para obtener token de autenticación

POST https://biometric.danaconnect.com/oauth2/token

Encabezados requeridos

Content-Type: application/x-www-form-urlencoded
Authorization: Basic <credenciales_base64>

Parámetros del cuerpo (form-urlencoded)

grant_type=client_credentials

Ejemplo de respuesta exitosa

{
  "access_token": "73wrW8sdfXsGsfBug",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Este token debe incluirse en el encabezado Authorization en las siguientes llamadas al API:

Authorization: Bearer <access_token>

Inicialización de un Circuito de Firma Biométrica

Permite iniciar la experiencia de un nuevo circuito de firma electrónica, asociando firmantes y documentos al proceso.

Endpoint

POST https://biometric.danaconnect.com/api/v1/biometric/start_circuit/{channel}

Encabezados requeridos

Content-Type: application/json
Authorization: Bearer <access_token>

Ejemplo de parámetros esperados en la solicitud

{
  "id": "2",
  "signer": {
    "name": "Jhon",
    "email": "john@example.com",
    "nif": "12345678A"
  },
  "docs": [
    {
      "name": "nombrearchivoejemplo.pdf",
      "size": 0,
      "content": "base64stringdelarchivo"
    }
  ]
}

channel: debe reemplazarse con el identificador único asignado al cliente por DANAconnect.
El campo content debe contener el archivo codificado en Base64.

Ejemplo de respuesta exitosa

{
  "circuitId": "658936",
  "link": "https://example.esignature-platform.com/sign/658936"
}

El campo link contiene la URL a la experiencia web a la que se debe dirigir al firmante para completar el proceso.

Recuperación de Documentos del Circuito

Una vez finalizado el proceso de firma, es posible recuperar todos los documentos firmados asociados al circuito en un archivo .zip.

Endpoint de descarga

GET https://{subdomain}.esignature-platform.com/api/v1/biometric/document_circuit/{channel}/circuit/{circuit_id}

Encabezados requeridos

Content-Type: application/zip
Authorization: Bearer <access_token>

Parámetros

channel: identificador del cliente.

circuit_id: ID del circuito generado previamente.

Este endpoint no requiere cuerpo en la solicitud ( request body: none). La respuesta será directamente un archivo comprimido con los documentos.

Códigos de Error Comunes

Código HTTP	Estado	Descripción
200	OK	La solicitud fue procesada correctamente.
400	Bad Request	Error en la solicitud. Parámetros mal formateados o incompletos.
401	Unauthorized	Token de acceso inválido, vencido o no proporcionado en la cabecera.

Descripción del flujo del proceso

---

Consideraciones Finales

Todos los endpoints deben ser consumidos utilizando el protocolo HTTPS.
Las credenciales y tokens deben ser almacenados y transmitidos de forma segura.
Cualquier integración debe pasar por pruebas en un ambiente de staging antes de ser implementada en producción.
El proceso de videofirma está diseñado para cumplir con altos estándares de seguridad y trazabilidad.

Actualizado el: 14/04/2025