Sesión biométrica embebida

curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric/sessions \
  --header 'Authorization: Bearer <token>'

import requests

url = "http://api.gu1.ai/api/kyc/biometric/sessions"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/biometric/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/biometric/sessions"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/biometric/sessions")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/biometric/sessions")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

POST

api

kyc

biometric

sessions

Sesión biométrica embebida

curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric/sessions \
  --header 'Authorization: Bearer <token>'

import requests

url = "http://api.gu1.ai/api/kyc/biometric/sessions"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/biometric/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/biometric/sessions"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/biometric/sessions")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/biometric/sessions")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Resumen

Biometría embebida permite re-verificar que quien completa un flujo es la misma persona que aprobó el KYC. A diferencia del chequeo biométrico síncrono, acá Gu1 devuelve un sessionUrl con UI hospedada de captura. Tu app lo embebe en un iframe (o redirige) para que el liveness ocurra en un entorno controlado.

Usá status de la API o del webhook como resultado biométrico. Gu1 gestiona el ciclo completo de la sesión y puede devolver rejected tras políticas de la organización (cruces entre entidades, umbrales de face match).

Requisitos

KYC aprobado en Gu1 para la entidad persona.
Retrato de referencia disponible desde ese KYC.
KYC habilitado en tu organización (misma API key y permisos que la validación por sesión). La configuración interna de captura biométrica embebida la provisiona el equipo Gu1; como integrador no configurás workflows ni credenciales adicionales. Si la org aún no fue habilitada, POST /api/kyc/biometric/sessions puede responder BIOMETRIC_WORKFLOW_NOT_CONFIGURED (400) — contactá a tu contacto Gu1.
Gu1 Biometría activo para tu organización (global_gueno_biometric_kyc). Si no está habilitado, la API responde NOT_ENABLED (403) — solicitá la activación a Gu1.

Crear sesión

POST /api/kyc/biometric/sessions Parámetros clave: entityId, entityExternalId o entityTaxId (exactamente uno requerido), webhookUrl (opcional), callback, language. Flujo face match (liveness + comparación contra retrato del KYC aprobado; NO_PORTRAIT si falta selfie).

Vista previa sandbox (solo GET): GET /api/entities/by-tax-id/{taxId} puede devolver una persona sintética (sandboxMock: true, id: null) para números de prueba del catálogo cuando no hay fila real. Es solo lectura — para POST /sessions necesitás una entidad persistida.

Respuesta 201: id, sessionUrl, iframeAllow, hostedSessionId, status (pending en flujo real; approved / rejected inmediato en mock sandbox). Ver mock sandbox.

Flujo recomendado de integración

Entidad persona con KYC approved.
POST /api/kyc/biometric/sessions una vez por intención del usuario. Guardá id, sessionUrl y hostedSessionId.
Si responde 409 ACTIVE_SESSION_EXISTS, cancelá con POST .../sessions/{activeSessionId}/cancel y recién ahí creá de nuevo (no reintentar en loop sin manejar el 409).
Si status es pending, embebé sessionUrl en iframe (o redirigí).
Esperá webhooks biometric.session_* (o GET .../sessions/:id / POST .../sync si hace falta).
Usá status y rejectionCode como resultado final.

No uses reintentos repetidos de POST /sessions como flujo normal. Tras timeout o doble click pueden aparecer casos borde de idempotencia. Siempre manejá 409, cancelá sesiones activas explícitamente y preferí webhooks sobre polling agresivo.

Errores al crear (`POST /sessions`)

HTTP	`error`	Cuándo	Qué hacer
400	`NO_KYC`	No hay KYC aprobado	Completar KYC primero
400	`NO_PORTRAIT`	KYC aprobado sin selfie de referencia (flujo real)	Repetir KYC con captura válida o usar mock sandbox
400	`KYC_NOT_CONFIGURED`	Credenciales KYC faltantes	Configurar KYC en la org
400	`ENTITY_NOT_FOUND`	`entityId` inválido u org incorrecta	Corregir entidad / `X-Organization-ID`
400	`INVALID_ENTITY_TYPE`	Entidad no es `person`	Usar entidad persona
403	`NOT_ENABLED`	Biometría no activa en marketplace	Pedir activación a Gu1
402	`INSUFFICIENT_CREDITS_FOR_KYC`	Sin créditos/pack	Recargar billing
409	`ACTIVE_SESSION_EXISTS`	Última sesión `pending` / `in_progress`	Cancelar `activeSessionId` y crear de nuevo
502	`PROVIDER_ERROR`	Gu1 no pudo iniciar la captura hospedada	Reintentar más tarde; usar código `error` y HTTP status
500	`CREATION_FAILED`	Fallo inesperado al persistir	Revisar logs; cancelar sesión colgada; un reintento

Ejemplo 409 ACTIVE_SESSION_EXISTS (aditivo — clientes que ignoran campos extra no cambian):

{
  "error": "ACTIVE_SESSION_EXISTS",
  "message": "Cannot create new biometric session. There is already a pending session for this entity. Please cancel or complete the existing session first.",
  "activeSessionId": "7618e10c-b1b1-408b-b361-1901077ced73"
}

Repetir POST /sessions con una sesión aún abierta siempre devuelve este 409. Gu1 no responde 201 con la misma sesión pending.

Sesiones previas y “actual”

Una entidad puede tener varias sesiones biométricas (aprobadas, rechazadas, canceladas).

API	Significado
`GET .../entities/:entityId/current`	Última creada (cualquier estado) — recuperar iframe pendiente
`GET .../entities/by-tax-id/:taxId/current`	Igual, resuelto por `entityTaxId`
`GET .../entities/by-external-id/:externalId/current`	Igual, resuelto por `entityExternalId`
`GET .../sessions?entityId=...` (o `entityTaxId` / `entityExternalId`) → `currentSessionId`	Última sesión `approved` — verificación vigente
Listado `data[]`	Historial por `createdAt`

Una sesión aprobada anterior no bloquea crear otra. Solo bloquea una sesión activa (pending / in_progress) → 409.

`hostedSessionId`, cancelación y reintentos

hostedSessionId es la referencia de sesión de captura hospedada devuelta al crear. Gu1 la guarda de forma única para webhooks y sync. Recuperación correcta: 409 → cancelar activeSessionId → un solo POST nuevo. Tras cancelar, podés crear una sesión nueva. La persistencia idempotente (reutilizar una fila terminal existente si vuelve el mismo hostedSessionId) aplica solo después del cancel u otros outcomes terminales — no mientras la sesión siga pending o in_progress. Mock sandbox: prefijo sandbox-mock-bio-; cada create mock genera un ID nuevo.

Embeber

<iframe
  src="{{ sessionUrl }}"
  style="width: 100%; height: 700px; border: none;"
  allow="{{ iframeAllow }}"
></iframe>

Consultar estado

GET /api/kyc/biometric/sessions/:id — una sesión por ID
GET /api/kyc/biometric/entities/:entityId/current — sesión actual = la más reciente por createdAt. Responde 200 con null si no hay sesiones.
GET /api/kyc/biometric/entities/by-tax-id/:taxId/current — igual, resuelto por tax ID
GET /api/kyc/biometric/entities/by-external-id/:externalId/current — igual, resuelto por external ID
GET /api/kyc/biometric/sessions?entityId=... — listado; también acepta entityTaxId o entityExternalId (uno a la vez). currentSessionId es la última sesión approved.
POST /api/kyc/biometric/sessions/:id/sync
POST /api/kyc/biometric/sessions/:id/cancel — cancela manualmente sesiones pending o in_progress (marca cancelled en Gu1).
GET /api/kyc/biometric/sessions/:id/media?key= — imágenes persistidas referenciadas en decision.

Si POST /sessions responde 409 ACTIVE_SESSION_EXISTS, el cuerpo incluye activeSessionId para cancelar sin consultar /current.

La plataforma puede reportar In Review durante la revisión de la captura; en Gu1 eso se refleja como in_progress hasta el veredicto final (approved o rejected). Solo los estados terminales de resultado cuentan para definir la sesión actual.

Webhooks

webhookUrl por request — si lo enviás al crear la sesión.
Webhooks de organización — eventos biometric.session_*. Ver eventos biométricos.

Para autenticación reforzada en login o step-up, preferí sesiones embebidas frente al endpoint síncrono.

Sesiones mock en sandbox

En sandbox, si la entidad tiene un KYC mock aprobado (taxId de prueba como 99990001, o KYC con metadata.sandboxMock: true), POST /api/kyc/biometric/sessions puede devolver un resultado mock inmediato (approved o rejected) sin captura hospedada.

Por defecto: 99990001 → biometría approved; 99990011 → biometría rejected (KYC sigue approved).
Override: "metadata": { "sandboxMockOutcome": "rejected" } en cualquier entidad elegible.
Las respuestas mock usan hostedSessionId con prefijo sandbox-mock-bio- y pueden traer status: approved o rejected en el create (no solo pending).

Tablas y ejemplos completos: Datos mock sandbox — Biometría embebida.

Obtener imágenes Face Match Obtener sesión biométrica actual

⌘I

Comenzando

SDK

Casos de Uso

Webhooks

Workflows

Monitoreo (entidades)

Persona

Mensajería

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Listas personalizadas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Importaciones masivas

Documentos

Enriquecimiento

Servicios

Integraciones

Tutoriales Interactivos

Sesión biométrica embebida

Resumen

Requisitos

Crear sesión

Flujo recomendado de integración

Errores al crear (`POST /sessions`)

Sesiones previas y “actual”

`hostedSessionId`, cancelación y reintentos

Embeber

Consultar estado

Webhooks

Sesiones mock en sandbox

​Resumen

​Requisitos

​Crear sesión

​Flujo recomendado de integración

​Errores al crear (POST /sessions)

​Sesiones previas y “actual”

​hostedSessionId, cancelación y reintentos

​Embeber

​Consultar estado

​Webhooks

​Sesiones mock en sandbox

Resumen

Requisitos

Crear sesión

Flujo recomendado de integración

Errores al crear (`POST /sessions`)

Sesiones previas y “actual”

`hostedSessionId`, cancelación y reintentos

Embeber

Consultar estado

Webhooks

Sesiones mock en sandbox