API Envío de Verificación de Identidad (3.0)

INTRODUCCION

API de integración de servicios de verificación de Identidad mediante peticiones API REST.

COMPATIBILIDAD Y VERSIONES


Versión 1.0 – 1.7: Última actualización 2017. Se recomienda la actualización a versión 3.0 o superior. Versiones no soportadas actualmente. Contactar con soporte para ayuda a la migración.
Versión 2.0 – 2.3: última actualización: 2019. Se añaden parámetros a las peticiones para utilizar más posibilidades de firma, sello de tiempo y contratación. Se añade el servicio de verificación/certificación de identidad online mediante vídeo.

Versión 2.5: última actualización: 2020. Se añade la posibilidad de envío de verificación de identidad en los contratos y parámetros identificativos del contrato.
Versión 2.55: Última actualización: 2021. Se añade una utilidad para certificar y sellar en tiempo o sólo sellar un documento PDF de forma sencilla. Utilidad integrable en aplicaciones.
Versión 3.0: Última actualización 2021. Se cambia el formato de API REST para adecuar los sistemas a la certificación de seguridad ENS (esquema nacional de seguridad). Se añade la posibilidad de uso de flujos de trabajo y se amplían las posibilidades de personalización. Se añade la posibilidad de añadir recuadros de firma en plantillas y ficheros y otras funcionalidades. Se recomienda la migración a esta versión. La migración es muy sencilla desde 2.0 o superior.

AUTENTICACIÓN

En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las Peticiones, por seguridad deben ralizarse en POST y con protocolo HTTPS Seguro.

Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.

Para generar el string codificado en Base64, simplemente genere el string UsuarioApi:APIToken y codifíquelo en base64 mediante cualquier función base64encode.

A TENER EN CUENTA

Conexiones en vacío: Es importante tener en cuenta que una conexión errónea de forma repetida será tratada por el sistema como spam y podrá llegar a bloquear temporalmente la conexión. Es conveniente evitar realizar repetidas conexiones con datos erróneos o conexiones rápidas ‘en vacío’ (sin realizar envíos) con los mismos datos para obtener el número de créditos o el mismo report.

Para obtener reports de forma óptima en tiempo real se recomienda configurar la API en el panel para recibirlos en un script de su web.
Respuesta de las peticiones: La mayoría de las funciones disponen de un parámetro denominado ‘Resp’. Este parámetro define el formato de la respuesta que se devolverá. Puede ser TXT, JSON, XML o no definido. Se recomienda siempre definir este parámetro ya que todas las funciones, por compatibilidad con versiones anteriores de la API, responden por defecto (si no se define este parámetro) tal y como lo hacían en versiones antiguas. En estos resultados de versiones de API anteriores se obvian algunas de las variables que se incluyen en esta versión de la API y que consideramos importantes para facilitar la integración e información de la cuenta. En los ejemplos incluidos siempre se tiene en cuenta que ha definido el parámetro. Si está trabajando directamente con la API versión >= 5, asumiremos que ha definido el parámetro en todas las peticiones.
Funcionamiento recomendado: El funcionamiento recomendado, por ser el más sencillo y, a la vez, el más profesional es el siguiente:
- PROCESO 1: Envío de Petición de verificación de Identidad al usuario: Descrito en la función /VerificarIdentidad de este documento.
- PROCESO 2: Recepción automática de resultado en su web mediante webhook (proceso descrito en el la sección 'Recepción automática de eventos'.

Enviar Petición de Verificación de Identidad

/VerificarIdentidad

Función de envío de peticiones de Verificación de identidad mediante vídeo e Inteligencia Artificial. Definición de parámetros necesarios.

ATENCIÓN: Chequee la sección de recepción de eventos en tiempo real si desea recibir el estado de la verificación y las interacciones del destinatario en tiempo real en un script de su web.

query Parameters
Mensaje
string
Example: Mensaje=MiEmpresa

Es el mensaje que se le enviará al destinatario a su móvil con el link para comenzar el proceso. Debe incluir la palabra clave [LINK] que se sustituirá por el link de acceso. Por ejemplo: 'Necesitamos verificar su identidad. Pulse en el siguiente link para comenzar el proceso: [LINK].’

Dni
string
Example: Dni=00000000T

Si lo desea, puede indicar el número de DNI a verificar, el sistema verificará a la persona, su DNI e indicará en el resultado, adicionalmente, si el DNI es el esperado.

Fecha
string
Example: Fecha=2022-05-01 15:10

Fecha en la que queda programado el envío de la petición de verificación de identidad. Por defecto "" que significa enviar inmediatamente. Formato Año-Mes-dia hora:minuto. La referencia horaria es CET/CEST (Zona horaria de España).

Remitente
string
Example: Remitente=MiEmpresa

Remitente de los SMS enviados para el comienzo del proceso. Es lo que recibirá en el móvil cada destinatario como 'mensaje de...'. Por lo general se utiliza el nombre de la empresa emisora. Máximo 11 caracteres.

Telefono
string
Example: Telefono=34600000001

Teléfono móvil del destinatario.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array ()
Res
required
integer <int32>

Respuesta de la función solicitada
1 Correcto.
-1 Error de autenticación.
-2 No hay céditos suficientes en la cuenta.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-4 Su cuenta no tiene activada la posibilidad de uso de esta función, es necesario que valide la cuenta antes de utilizarla. Contacte con soporte.
-5 a -7 Error general en la petición (contacte con soporte indicando los parámetros utilizados).

ID
string

Identificador de la petición enviada. (Ver recepción de Eventos en este documento)

Cred
integer

Créditos que restan en la cuenta de usuario tras el envío.

Request samples


curl --location --request POST 'https://www-lofirmo.com/api/v3/VerificarIdentidad' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 

Response samples

Content type
[
  • {
    }
]

Recepción de reports de entrega y cambios de estado de peticiones enviadas

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

RECEPCIÓN EN TIEMPO REAL DE LOS ESTADOS EN UN SCRIPT DE SU SERVIDOR. Activando la opción de recibir los reports en tiempo real en un script en su servidor desde su panel de usuario, recibirá una petición POST con el formato indicado cada vez que cada petición enviada cambie de estado. Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA

Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de report que está recibiendo (el objetivo es distinguir entre los reports de los diferentes servicios). Los servicios a los que se refiere esta especificación puede recibir VERIFICACION_IDENTIDAD Si el servicio se refiere a un cambio de estado de una petición de verificación de Identidad enviada.

ID
required
string

Identificador de la petición recvibida como respuesta a la función de Envío.

FechaEnvio
string

Fecha en la que se envió la petición.

Estado
required
integer

Estado de la petición. Los estados posibles son:

ESTADO DESCRIPCION SIGNIFICADO
`3000` El usuario ha accedido El usuario ha accedido para comenzar el proceso.
`3001` Verificando Persona/Prueba de vida Se está verificando a la persona mediante vídeo y se está realizando una prueba de vida.
`3002` Solicitud de Anverso DNI Tras la verificación de la persona, se solicita el anverso del DNI o pasaporte.
`3003` Solicitud reverso DNI Se ha solicitado al usuario que muestre el reverso de su DNI.
`5000` En proceso El servicio está aceptado y en proceso de verificación.
`5001` Proceso en verificación Se ha finalizado el proceso y tiene disponibles los datos (los recibirá en variables y dispone en el panel de la información..
`5100` Validado La verificación ha sido validada y certificada. Puede descargar el certificado mediante la función de descarga.
`5500` Rechazado La verificación ha sido rechazada por un operador en base a los resultados obtenidos. Recibirá los datos y el motivo como parámetros.
UltimaActualizacion
string

Última actualización/interacción con el usuario.

Acceso
array

Array con fecha y dirección IP de acceso del destinatario. Se recibirán los siguientes datos en JSON:
Fecha : Fecha de Acceso
IP : IP desde la que accede al servicio
Puerto : Puerto desde el que se conecta el destinatario

Ejemplo: {"Fecha":"2021-09-04 19:37:21","IP":"85.10.20.221","Puerto":"11892"}

Telefono
integer

Número de Móvil del destinatario.

DNIAnverso
string

Si ya está disponible en el momento de esta petición se enví el número de DNI detectado en el anverso del documento durante el proceso.

DNIReverso
string

Si ya está disponible en el momento de esta petición se enví el número de DNI detectado en el reverso del documento durante el proceso. Lógicamente, debería coincidir con el número del reverso para ser correcto

DNISolicitado
string

Si, durante la petición se solicitó verificar un número determinado de DNI para el destinatario, aquí se indicará.

Posicion
array

Array con la ubicación del destinatario si éste lo ha permitido durante el proceso. Se recibirán los siguientes datos en JSON
Direccion : Calle y número donde se encuentra el destinatario
Coordenadas : Latitud, longitud y altitud de la localización, incluyendo la precisión en metros en forma de JDON:
         Longitud : Longitud
         Latitud : Latitud
         Altura : Altura
         Precision : Precision de la localización GPS

Ejemplo: {"Direccion":"C. de las calles, 8B, 28333 Madrid, Spain","Coordenadas":{"Longitud":"-1.6592592","Latitud":"4.4577993","Altura":75.70229058041491,"Precision":15.265999794006348}}

Dispositivo
array

Array con fdatos del dispositivo uutilizado (móvil del destinatario). Se recibirán los siguientes datos en JSON:
browser : Explorador utilizado y versión
SysOp : Sistema operativo del dispositivo utilizado y versión
displayResolution : Resolución de la pantalla del dispositivo utilizado.

Ejemplo: {"browser":"Chrome 92.0.4515.131","SysOp":"Android 11","displayResolution":"360 x 800"}

Result
array

Array con los datos del resultado de la Verificación de Identidad. Se recibirán los siguientes datos en JSON:
Resultado : Puede ser positivo (>80) en cuyo caso todo ha salido correctamente o <0 en cuyo caso, se da una de las razones de error. También se incluyen todos los datos para verificar los motivos de fallo.
       >80 Parecido en porcentaje (80-100%) entre persona y DNI, si el porcentaje es menor debe validarse manualmente (operador)
       -1 El parecido es menor que 80% y debe ser validado por un operador (en base a los datos, fotos clave, dni, y resultados que aparecen en el panel de usuario o mediante los datos recibidos en esta petición).
       -2 El destinatario es menor de edad.
       -3 El Anverso y Reverso del documento no parecen coincidir.
       -4 La prueba de vida parece haber sido realizada por distintas personas.
       -5 DNI Caducado.
       -6 La prueba de vida no ha obtenido un resultado válido (es una foto?).
       -7 Proceso aún no finalizado.
       -8 El destinatario muy distinto a la foto del DNI o el DNI no es válido
       -9 Se solicitó verificar un número de DNI que no coincide con el aportado por el destinatario.
DNIAnverso : Sistema operativo del dispositivo utilizado y versión
DNIReverso : Resolución de la pantalla del dispositivo utilizado.
AnversoReversoCoinciden : Puede ser Si o No
DNISolicitado : Resolución de la pantalla del dispositivo utilizado.
DNISolicitadoCoincide : Puede ser Si, No o N/A si no se envió un número DNI en la petición
DNI : Datos del DNI verificado, se incluyen los siguientes datos:
       Edad : Edad real
       FechaNacimiento: Fecha de nacimiento
       DNI: Número de DNI que aparece en el documento
       Nacionalidad: Nacionalidad de la persona
       Pais: País
       Nombre: Nombre complet en formato Apellidos, Nombre
       NumeroSerie: Número de serie del documento
       TipoDocumento: Tipo de documento
       Sexo : Sexo F Mujer, M Hombre
       FechaExpira : Fecha en la que el documento expira.
       Caducado : Puede ser Si o No
ProcesoRelizadoMismaPersona : Puede ser Si o No
Barba : Puede ser Si o No
Bigote : Puede ser Si o No
GafasLectura : Puede ser Si o No
GafasSol : Puede ser Si o No
Sexo : Indica el sexo aparente y la probabilidad de que sea el sexo indicado, por ejemplo: Hombre con probabilidad de 98.599784851074%
RangoAparenteEdad : Rango aparente de edad, por ejemplo 40-50
Dispositivo : Resumen del dispositivo utilizado.
ParecidoPersonaDNI : Porcentaje de parecido entre persona y DNI. Ejemplo: 93.957847595214844
PruebaDeVida : Indica si ha pasado la prueba de vida. Puede ser Si o No.

Ejemplo: {"Resultado":93.957847595214844,"DNIAnverso":"00000000T","DNIReverso":"00000000T","AnversoReversoCoinciden":"Si","DNISolicitado":"","DNISolicitadoCoincide":"N/A","DNI":{"Edad":66,"FechaNacimiento":"18/12/1955","DNI":"00000000T","Nacionalidad":"ESP","Pais":"ESP","Nombre":"APARICIO LOPEZ,JUAN","NumeroSerie":"BGHR56776","TipoDocumento":"ID-1","Sexo":"M","FechaExpira":"19/10/2027","Caducado":"No"},"ProcesoRelizadoMismaPersona":"Si","Barba":"No","Bigote":"No","GafasLectura":"No","GafasSol":"No","Sexo":"Hombre con probabilidad de 99.599784851074%","RangoAparenteEdad":"44-62","Dispositivo":"Android.v11-Chrome.v92.0.4515.131","ParecidoPersonaDNI":93.957847595214844,"PruebaDeVida":"Si"}

Request samples

Content type
{
  • "Servicio": "VERIFICACION_IDENTIDAD",
  • "ID": 299846332,
  • "FechaEnvio": "2021-10-10 10:10",
  • "Estado": 5001,
  • "UltimaActualizacion": "2021-10-10 10:10",
  • "Acceso": {
    },
  • "Telefono": 34600000000,
  • "DNIAnverso": "00000000T",
  • "DNIReverso": "00000000T",
  • "DNISolicitado": "00000000T",
  • "Posicion": {
    },
  • "Dispositivo": {
    },
  • "Result": {
    }
}

Consulta y descarga PDF Certificado con la Identificación

/GetCertificadoIdentidad

Obtención del fichero PDF con el certificado del proceso de verificación de identidad enviado mediante la API. Esta función se ejecuta, habitualmente, como respuesta a una recepción de report con estado de certificado (Estado 5100) . Se descarga directamente el fichero PDF si la función se ejecuta con éxito.

query Parameters
Id
required
integer
Example: Id=1283876988

Identificador ID devuelto en la función de envío.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
string

Request samples


curl --location --request POST 'https://www-lofirmo.com/api/v3/GetCertificadoIdentidad' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Id="1283876988"' \ 

Response samples

Content type
En caso de éxito se descarga un fichero PDF con el certificado del contrato.

Consulta de Créditos

/GetCreditos

Función que devuelve el número de créditos en la cuenta. Es una función de uso muy esporádico ya que la mayoría de las funciones devuelven en sus respuestas el número de Créditos restante en el usuario. Por tanto, se suele utilizar simplemente como prueba de funcionamiento o para obtener el número de créditos de forma ocasional

query Parameters
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array ()
Res
required
integer <int32>

Respuesta de la función solicitada
1 La función concluyó con éxito.
-1 Error de autenticación.

Cred
required
double

Créditos que restan en la cuenta de usuario tras el envío.

Request samples


curl --location --request POST 'https://www-lofirmo.com/api/v3/GetCreditos' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 

Response samples

Content type
[
  • {
    }
]