Download OpenAPI specification:Download
API de integración de servicios de verificación de Identidad mediante peticiones API REST.
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 incluye 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.
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.
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'.
Autenticación HTTP Basic. Use su Usuario API como usuario y su API Token como contraseña (los encuentra en su panel, en Tus Datos → Configurar Cuenta). El header resultante es Authorization: Basic base64(UsuarioAPI:APIToken). La mayoría de las librerías HTTP lo construyen automáticamente (curl -u, requests auth=, basic_auth de Ruby, etc.) sin necesidad de codificar el base64 a mano.
basicFunció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.
| 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 required | 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.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Mensaje | string |
| Dni | string |
| Fecha | string |
| Remitente | string |
| Telefono required | string |
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| 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. |
{- "Mensaje": "MiEmpresa",
- "Dni": "00000000T",
- "Fecha": "2022-05-01 15:10",
- "Remitente": "MiEmpresa",
- "Telefono": "34600000001",
- "Resp": "JSON"
}[- {
- "Res": "10",
- "ID": "1994779988",
- "Cred": "12000"
}
]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
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
| |||||||||||||||||||||||||||
| 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:
| |||||||||||||||||||||||||||
| UltimaActualizacion | string Última actualización/interacción con el usuario. | |||||||||||||||||||||||||||
| Acceso | Array of arrays Array con fecha y dirección IP de acceso del destinatario. Se recibirán los siguientes datos en JSON:
| |||||||||||||||||||||||||||
| 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 of arrays Array con la ubicación del destinatario si éste lo ha permitido durante el proceso. Se recibirán los siguientes datos en JSON
| |||||||||||||||||||||||||||
| Dispositivo | Array of arrays Array con fdatos del dispositivo uutilizado (móvil del destinatario). Se recibirán los siguientes datos en JSON:
| |||||||||||||||||||||||||||
| Result | Array of arrays Array con los datos del resultado de la Verificación de Identidad. Se recibirán los siguientes datos en JSON:
|
{- "Servicio": "VERIFICACION_IDENTIDAD",
- "ID": "299846332",
- "FechaEnvio": "2021-10-10 10:10",
- "Estado": "5001",
- "UltimaActualizacion": "2021-10-10 10:10",
- "Acceso": "{\"Fecha\":\"2021-09-04 19:37:21\",\"IP\":\"85.10.20.221\",\"Puerto\":\"11892\"}",
- "Telefono": "34600000000",
- "DNIAnverso": "00000000T",
- "DNIReverso": "00000000T",
- "DNISolicitado": "00000000T",
- "Posicion": "{\"Direccion\":\"C. de las calles, 8B, 28333 Madrid, Spain\",\"Coordenadas\":{\"Longitud\":\"-1.6592592\",\"Latitud\":\"4.4577993\",\"Altura\":75.70229058041491,\"Precision\":15.265999794006348}}",
- "Dispositivo": "{\"browser\":\"Chrome 92.0.4515.131\",\"SysOp\":\"Android 11\",\"displayResolution\":\"360 x 800\"}",
- "Result": "{\"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 GARCIA,RAFAEL\",\"NumeroSerie\":\"BGT78666\",\"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\"}"
}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.
| 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.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Id required | integer |
| Resp | string |
{- "Id": "1283876988",
- "Resp": "JSON"
}En caso de éxito se descarga un fichero PDF con el certificado del contrato.
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
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| Cred required | double Créditos que restan en la cuenta de usuario tras el envío. |
{- "Resp": "JSON"
}[- {
- "Res": "10",
- "Cred": "12000"
}
]