Obtener datos de biometría

Cuando un firmante completa una validación biométrica, Signatura almacena los datos obtenidos durante el proceso de verificación. Este tutorial explica cómo obtener esos datos utilizando la API.

Requisitos previos

Para obtener los datos de biometría de una firma, necesitas:

• Una API key válida
• El ID de la firma (signature_id) que utilizó validación biométrica
• La firma debe estar completada (status CO)

Endpoint

GET /api/v2/signatures/{id}/biometrics
Authorization: Bearer <apikey>

El parámetro {id} corresponde al UUID de la firma de la cual deseas obtener los datos biométricos.

Ejemplo de solicitud

curl -X GET "https://connect.signatura.co/api/v2/signatures/f5407940-6d19-4508-baed-195c03fcf739/biometrics" \
  -H "Authorization: Bearer <apikey>"

Ejemplo de respuesta

{
  "full_name": "Juan Pérez",
  "document_number": "12345678",
  "country": "Argentina",
  "photos": [
    {
      "url": "https://example.org/front.jpg",
      "type": "front"
    },
    {
      "url": "https://example.org/back.jpg",
      "type": "back"
    },
    {
      "url": "https://example.org/selfie.jpg",
      "type": "selfie"
    }
  ],
  "attempts": 1
}

Campos de la respuesta

Campo	Tipo	Descripción
full_name	string	Nombre completo del firmante según el documento de identidad
document_number	string	Número del documento de identidad
country	string	País de emisión del documento
photos	array	Lista de fotos capturadas durante la verificación
photos[].url	string	URL de la imagen
photos[].type	string	Tipo de foto: front (frente del documento), back (reverso) o selfie
attempts	integer	Número de intentos de verificación realizados

Cómo obtener el ID de la firma

Para obtener los datos biométricos, primero necesitas el ID de la firma. Puedes obtenerlo de varias formas:

1. Al crear el documento

Cuando creas un documento con validación biométrica, la respuesta incluye los IDs de las firmas:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "signatures": [
    {
      "id": "f5407940-6d19-4508-baed-195c03fcf739",
      "validations": {
        "BI": {"value": "AR:12345678", "validated": false}
      },
      "status": "IN"
    }
  ]
}

2. A través del webhook de firma completada

Cuando se completa una firma, Signatura envía una notificación webhook con el signature_id:

{
  "notification_action": "DS",
  "document_id": "072b39ab-05f2-46aa-b093-e13ff824752b",
  "signature_id": "f5407940-6d19-4508-baed-195c03fcf739"
}

3. Consultando el documento

Puedes obtener los IDs de las firmas consultando los detalles del documento:

GET /api/v2/documents/{document_id}
Authorization: Bearer <apikey>

Códigos de respuesta

Código	Descripción
200	Datos biométricos obtenidos correctamente
400	Error en la solicitud
404	No existen datos biométricos para la firma especificada
429	Demasiadas solicitudes (rate limiting)

Notas importantes

• Los datos biométricos solo están disponibles para firmas que utilizaron la validación BI.
• Las URLs de las fotos tienen una validez limitada. Descárgalas y almacénalas en tu sistema si necesitas conservarlas.
• Signatura puede agregar campos adicionales a esta respuesta en el futuro. Asegúrate de que tu implementación maneje campos desconocidos correctamente.
• Evita consultar este endpoint de forma repetida (polling). Utiliza webhooks para recibir notificaciones cuando una firma se complete.