API de integración de servicios de contratación, envío de documentos para firma desde aplicaciones 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.
Versión 3.1: Última actualización 2023. Se añade la posibilidad de solicitar documentos a los firmantes.
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.Función de envío de contratos y configuración del mismo para su firma por uno o varios firmantes. 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 los contratos y las interacciones del/ de los firmantes en tiempo real en un script de su web.
| Firmantes required | Array of arrays Example: Firmantes=[{"Nombre":"Pedro Pérez","NIF":"00000000T","Email":"destinatario@eldominio.com"}]
Array JSON con los datos de los firmantes. Dn el que se deben incluir lss siguientes variables: |
| Flujotrabajo | string Example: Flujotrabajo=238754787
Flujo de trabajo ya guardado en su cuenta y que desea reutilizar. Un flujo de trabajo se crea desde su panel de usuario al enviar contratos para firma, tiene predefinidos los documentos, plantillas, tipo de firma, etc... y basta con definir los destinatarios/firmantes para completar el proceso. Es muy útil en envíos de tipos de contrato de tipo repetitivo (plantillas de contrato como condiciones particulares, PDF en condiciones generales y una plantilla SEPA por ejemplo). La utilización de Flujos de trabajo sólo añade los valores definidos si no se envían en la petición, es decir, las variables normales , por ejemplo TipoFirma, prevalecen en la petición frente a la definida en el flujo de trabajo. Así, si en el flujo de trabajo ha definido ACEPTACION como modo de firma y en la petición API no se define, se utilizará ese tipo de firma pero, si , por ejemplo, en la petición define TipoFirma=BIOMETRICA, ésta prevalecerá(se utilizará) sobre la definida en el flujo de trabajo. Hay dos variables cuyo funcionamiento es distinto. DOCUMENTOS y FIRMASEMISOR añaden los documentos y firmas definidos tanto en el flujo de trabajo como en la petición. Estos parámetros, por tanto, son acumulativos. |
| Firmasemisor | Array of arrays Example: Firmasemisor=[{"ID":1865998}]
Array JSON con las firmas de emisor guardadas en su cuenta que desea 'imprimir' sobre las plantillas y documentos enviados tras la firma de los firmantes. El sistema, antes de la certificación añadirá su firma y certificados al documento completando el documento legal. Los recuadros de estampación de las firmas se definen en la variable documentos para PDFs y en la creación de plantillas en el panel de usuario para las Plantillas
|
| Documentos | Array of arrays Example: Documentos=[{"Tipo":"PLANTILLA","PLANTILLA":"120958967","ACEPTACION":"NO"}]
Array JSON con el listado de documentos, plantillas y casillas de verificación que componen el contrato o acuerdo. Los parámetros a incluit en el array son: |
| Documentossolicitados | Array of arrays Example: Documentossolicitados=[{"Texto":"Por favor, cargue o haga una foto del anverso de su DNI","Firmante":"0"}]
Array JSON con el listado de documentos que se solicitan a uno o todos los firmantes, se puede elegir que cada firmante suba un documento distinto , que todos suban el mismo (por ejemplo el DNI de cada firmante) o cualquier combinación. Los parámetros a incluir por cada documento solicitado son: |
| Personalizacion | string Example: Personalizacion={
"Nombre_de_Empresa":”La empresa”,
"CIF":”B800000000”,
"Nombre_Apoderado":”Pedro Fernández”,
"Variable …":”Valor”,
}
Array JSON con los datos de personalización de las plantillas si se han añadido una o varias plantillas y se desea que se rellenen de forma automática, debe indicar aquí los valores de cada variable que quiera rellenar. Las variables de la/las plantilla/s que no indique/especifique en este parámetro deberán ser rellenadas por el primer firmante. Por ejemplo: |
| Tipofirma | string Enum: 1 2 3 4 Example: Tipofirma=3
Es el tipo de firma que deberán utilizar los firmantes. Las opciones son:
|
| Remitente | string Example: Remitente=MiEmpresa
Remitente de los SMS o SMS Certificados enviados para el perfeccionamiento del contrato. Es lo que recibirá en el móvil cada firmante como 'mensaje de...'. Por lo general se utiliza el nombre de la empresa emisora. Máximo 11 caracteres. |
| Mensaje | string Example: Mensaje=MiEmpresa
Es el mensaje que se le enviará a cada firmante con el link de firma. Se pueden utilizar variables (las que ha enviado con cada firmante) y debe incluir el tag [LINK] dentro del mensaje que se sustituirá por el link de firma. El valor por defecto de esta parámetro (si no se especifica) es: ‘A la Atención de [NOMBRE] con NIF [NIF], según lo acordado, le enviamos el contrato para su firma. Pulse en el siguiente link: [LINK] para comenzar el proceso.’ |
| Mediocomunicacion | string Enum: 1 2 3 Example: Mediocomunicacion=EMAIL
Es el medio de comunicación que se utilizará en el mensaje de firma.
|
| Tipodocumento | string Example: Tipodocumento=Contrato
(Por defecto ‘Contrato’). String con el tipo de contrato que estamos enviando. Es lo que se le indica al/a los firmante/s que van a firmar. Por ejemplo puede ser ‘Acuerdo de conciliación’, ‘Contrato’, ‘Mandato Sepa’, ‘Declaración parte seguro’, ‘Cesión de poderes’, etc….No influye en la operativa, simplemente es lo que se le indica a los firmantes. |
| Verificacionidentidad | string Enum: "NO" "SI" Example: Verificacionidentidad=NO
(Por defecto NO) si se establece a 'SI', el sistema identificará mediante vídeo a cada firmante y certificará la identificación incluyendo validez del DNI, si la persona identificada es real (prueba de vida) y si la persona identificada es la del DNI. Para ello, el sistema hará un vídeo de la persona a identificar y le solicitará que muestre a la cámara el DNI. Los datos del DNI del primer firmante pueden utilizarse también para rellenar, de forma automática las plantillas incorporadas en el contrato. ATENCIÓN debe solicitar activación de este servicio ya que, por temas de privacidad, debemos validar la empresa que va a utilizar este servicio. Posibles valores:
|
| Minparecidoverificacion | integer Example: Minparecidoverificacion=80
Es el mínimo parecido entre la persona identificada y su DNI para continuar el proceso de contrato automáticamente. En caso de que no se supere este umbral o que el proceso haya detectado algún problema (por ejemplo DNI Caducado) el sistema esperará a la validación en paneles para continuar con el proceso de firma. También recibirá automáticamente una petición a su script receptor de report con todos los datos del DNI y el resultado y validaciones. |
| Referenciausuario | string Example: Referenciausuario=NombreFirmante-NombreEmpresa-DNI
Referencia del usuario para el contrato. Sirve como referencia de usuario (lo recibirá dentro de los parámetros de las peticiones a su script de recepción de reports) y para buscar de foma cómoda cada contrato en los paneles. |
| Accesible | string Enum: "NO" "SI" Example: Accesible=SI
Indica si cada firmante tendrá acceso al documento firmado. Realmente tendrá acceso al certificado final con el documento firmado.
|
| Alternamedios | string Enum: "NO" "SI" Example: Alternamedios=SI
Si se establece en SI, le indica al sistema que alterne la comunicación entre SMS y Email en cada recordatorio de firma hasta que los firmantes hayan finalizado el proceso. De este modo, siempre que haya definido el Email y el Teléfono Móvil de cada firmante, el sistema enviará recordatorios de firma alternativamente por SMS y por Email consiguiendo así un incremento en las posibilidades de contacto si el destinatario/firmante tiene estropeado el móvil, apagado o no abre correo.
|
| Recordatorios | integer Example: Recordatorios=3
Es el número de días entre recordatorios de firma. Si cada firmante no ha finalizado el proceso, lo ha dejado a medias o no ha accedido aún, el sistema le envía cada X días un recordatorio para que finalice el proceso. El máximo número de recordatorios es de 10 tras lo cual el contrato expirará a no ser que la fecha indicada en el parámetro FechaLimite sea anterior a que se puedan enviar ese número de recordatorios. |
| Fechalimite | string Example: Fechalimite=2021-10-10
Es la fecha en la que el sistema dejará de enviar recordatorios si no se ha finalizado el proceso y cerrará el contrato como no firmado. ATENCIÓN: El contrato realmente expirará en cualquiera de estos eventos, el que suceda antes:
|
| Idioma | string Enum: "es" "pt" Example: Idioma=es
Es el idioma en el que se muestra el proceso de firma. Si necesita uno que no aparezca, contacte con nosotros. En estos momentos las posibilidades son:
|
| Minimocheck | integer Example: Minimocheck=1
Si ha incluido CheckBoxes en los documentos es el número mínimo de ellos que debe activar cada firmante (ON) antes de continuar el proceso. La utilizdad de Mínimo y Máximo para checkboxes podría ser:
|
| Maximocheck | integer Example: Maximocheck=1
Si ha incluido CheckBoxes en los documentos es el número máximo de ellos que debe activar cada firmante (ON) antes de continuar el proceso. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON
Tipo de respuesta a mostrar como resultado de la llamada.
|
| Res required | integer <int32> Respuesta de la función solicitada
|
| ContratoId | string Identificador de contrato. Se utiliza para identificaciones posteriores en llamadas a la API junto con ReportID. También recibirá este dato en los eventos recibidos en tiempo real sobre el estado del contrato. (Ver recepción de Eventos en este documento) |
| ReportId | integer Identificador de referencia/reports contrato. Se utiliza para identificaciones posteriores en llamadas a la API junto con el ContratoID (por ejemplo para descarga del Contrato Certificado). También recibirá este dato en los eventos recibidos en tiempo real sobre el estado del contrato. (Ver recepción de Eventos en este documento) |
| Cred | integer Créditos que restan en la cuenta de usuario tras el envío. |
| Firmantes | integer Número de firmantes del contrato. |
| Documentos | integer Número de documentos enviados (plantillas, PDFs y checkboxes). |
curl --location --request POST 'https://www.lofirmo.com/api/v3/EnviarContrato' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Firmantes="[{\"Nombre\":\"Pedro Pérez\",\"NIF\":\"00000000T\",\"Email\":\"destinatario@eldominio.com\"}]"' \
[- {
- "Res": 10,
- "ContratoId": 1994779988,
- "ReportId": 1994779988,
- "Cred": 12000,
- "Firmantes": 2,
- "Documentos": 0
}
]RECEPCIÓN EN TIEMPO REAL DE LOS ESTADOS DE CADA CONTRATO 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 contrato enviado 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
| ||||||||||||||||||||||||
| ContratoID | string Identificador del contrato. También se conoce como CSV (Código Seguro de Verificación). Una vez certificado, el contrato estará siempre disponible en https://www.lofirmo.com/csv/{ContratID} (por ejemplo: https://www.lofirmo.com/csv/ASYYFRE5492-HN776TFD) | ||||||||||||||||||||||||
| ReportID | integer Identificador único de todos los reports del contrato. | ||||||||||||||||||||||||
| Resultado required | integer Estado del contrato. Los estados posibles son:
| ||||||||||||||||||||||||
| FechaEnvio | string Fecha en la que se envió el contrato. | ||||||||||||||||||||||||
| FechaFirma | string Fecha en la que se firmó el contrato. | ||||||||||||||||||||||||
| NumFirmantes required | string Número de firmantes del contrato. | ||||||||||||||||||||||||
| NumFimados | string Número de firmantes que ya han firmado. | ||||||||||||||||||||||||
| Referencia required | string Referencia del usuario que se envió durante la petición de envío. | ||||||||||||||||||||||||
| TipoFirma | integer Tipo de firma que se va a realizar/se ha realizado. Los valores posibles son:
|
{- "Servicio": "CONTRATACION",
- "ContratoID": "ASYYFRE5492-HN776TFD",
- "ReportID": 299846332,
- "Resultado": 11,
- "FechaEnvio": "2021-10-10 10:10",
- "FechaFirma": "2021-10-10 10:10",
- "NumFirmantes": 2,
- "NumFimados": 1,
- "Referencia": "Su referencia si la indicó",
- "TipoFirma": 3
}Función para cancelar el contrato si éste no está finalizado. Se dejan de enviar recordatorios y el contrato queda cerrado/cancelado.
| Contratoid required | string Example: Contratoid=1283876988
Identificador ContratoID devuelto en la función de envío. |
| Reportid required | integer Example: Reportid=1283876988
Identificador ReportID 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.
|
| Res required | integer <int32> Respuesta de la función solicitada
|
| Cred | double Créditos que restan en la cuenta de usuario tras el envío. |
curl --location --request POST 'https://www.lofirmo.com/api/v3/CancelarCONTRATO' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Contratoid="1283876988"' \ --form 'Reportid="1283876988"' \
[- {
- "Res": 1,
- "Cred": 12000
}
]Función para obtener el estado actual de un contrato. Se recomienda utilizar el webhook definido anteriormente donde recibirá las actualizaciones en tiempo real de los cambios de estado de los contratos.
| Contratoid required | string Example: Contratoid=1283876988
Identificador ContratoID devuelto en la función de envío. |
| Reportid required | integer Example: Reportid=1283876988
Identificador ReportID 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.
|
| Res required | integer <int32> Respuesta de la función solicitada
|
| Estado | integer Estado del contrato indicado. Para ver una descripción del estado, verificar en la operación webhook de recepción de reports en un script de su web. |
| FechaEnvio | string Fecha de envío incial del contrato. |
| FechaFirma | string Fecha en nloa que se firmó el contrato. |
| Firmantes | integer Número de firmantes que deben firmar el/los documentos. |
| Firmados | integer Número de firmantes que ya han firmado el/los documentos. |
| Cred | integer Créditos que restan en la cuenta de usuario tras el envío. |
curl --location --request POST 'https://www.lofirmo.com/api/v3/ReportSimpleCONTRATO' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Contratoid="1283876988"' \ --form 'Reportid="1283876988"' \
[- {
- "Res": 1,
- "Estado": 1014,
- "FechaEnvio": "2021-10-10 10:10",
- "FechaFirma": "2021-10-10 10:15",
- "Firmantes": 2,
- "Firmados": 2,
- "Cred": 12000
}
]Obtención del fichero PDF con el certificado del contrato enviado mediante la API. Esta función se ejecuta, habitualmente, como respuesta a una recepción de report con estado de certificado (ejemplo resultado 1014 -firmado y certificado- . Se descarga directamente el fichero PDF si la función se ejecuta con éxito.
| Contratoid required | string Example: Contratoid=1283876988
Identificador ContratoID devuelto en la función de envío. |
| Reportid required | integer Example: Reportid=1283876988
Identificador ReportID 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.
|
curl --location --request POST 'https://www.lofirmo.com/api/v3/GetCertificadoCONTRATO' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Contratoid="1283876988"' \ --form 'Reportid="1283876988"' \
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.
|
| 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. |
curl --location --request POST 'https://www.lofirmo.com/api/v3/GetCreditos' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \
[- {
- "Res": 10,
- "Cred": 12000
}
]