Firma Seguro API (VersiĆ³n anterior)
VERSIONAMIENTO DEL DOCUMENTO
Fecha | VersiĆ³n | Autor | DescripciĆ³n |
---|---|---|---|
2021-09-10 | 0.1 | Cristhian David Sandoval Pazu | ElaboraciĆ³n de la versiĆ³n inicial. |
2021-10-22 | 1.1 | Cristhian David Sandoval Pazu | Ajuste "base64String": "Reemplazar por un string base 64 pdf " |
2022-06-13 | 1.2 | Erika Marcela Romero GĆ³mez | Agrega tabla que describe los parĆ”metros del objeto json requerido para la creaciĆ³n de un proceso y aƱade ejemplo para cada tipo de proceso. Agrega informaciĆ³n referente a los estados de un proceso. |
2022-08-05 | 1.3 | Richard Barboza | Agrega documentaciĆ³n V2 API para processcreatefull con el nuevo campo balanceType. |
2022-11-21 | 1.4 | Richard Barboza | Agrega dos nuevos parƔmetros al json: isHandWritten: Manuscrita isPhotographic: Fotografica |
APROBACIONES DEL DOCUMENTO
Fecha | VersiĆ³n | Aprobador | Dependencia / Cargo |
2021-09-10 | 1.0 | Cristhian Sandoval | Desarrollador lĆder I+D+I |
2021-09-10 | 1.0 | Danny Guarin | Director Desarrollo de Negocios |
2021-10-29 | 1.1 | Cristhian Sandoval | Desarrollador lĆder I+D+I |
2021-10-29 | 1.1 | Danny Guarin | Director Desarrollo de Negocios |
2022-06-13 | 1.2 | Daniel Giraldo | Analista de pruebas |
2022-08-07 | 1.3 | Daniel Giraldo | Analista de pruebas |
2022-11-21 | 1.4 | Daniel Giraldo | Analista de pruebas |
---|
DOCUMENTACIĆN SERVICIO WEB FIRMA SEGURO
Este documento establece la definiciĆ³n de los mĆ©todos y los valores establecidos como parĆ”metros para el consumo del aplicativo Firma Seguro API en sistemas externos o aplicaciones clientes.
TambiĆ©n se evidencian consideraciones y prerrequisitos necesarios para realizar una integraciĆ³n con otras soluciones.
TĆRMINOS GENERALES
1.1 Proceso
Un proceso es el conjunto de firmantes que tienen como propĆ³sito firmar electrĆ³nicamente un documento pdf.
Estados de un proceso:
Borrador (1): El proceso ha sido creado pero aĆŗn no tiene asociado un documento o firmantes.
Creado (2): El proceso ha sido creado satisfactoriamente con su documento y firmantes respectivos.
En proceso (3): El documento del proceso se encuentra parcialmente firmado.
Exitoso (4): El proceso ha finalizado exitosamente, es decir, todos los signatarios han firmado el documento.
Declinado (5): El proceso ha sido cancelado o anulado, por tanto ya no posee validez. Solo pueden tener estado declinado aquellos procesos que no hayan culminado exitosamente.
1.2 Estrategia Polling
Es una de las estrategias propuesta por Firma Seguro API para consultar el estado de un proceso periĆ³dicamente y si el proceso estĆ” terminado exitosamente retorna el documento pdf firmado en base 64.
1.3 Estrategia CallBack
Es una de las estrategias propuestas por Firma Seguro API para devolver el documento pdf firmado en base 64, en este caso es necesario que el sistema cliente implemente un end point al cual Firma Seguro API responderƔ cuando el proceso estƩ terminado exitosamente.
2. CREAR UN PROCESO.
Diagrama de secuencia āCreaciĆ³n de procesoā
2.1 Ir al link a la pƔgina
https://demo.firmaseguro.co/api/swagger/index.html
2.2 Ir a la secciĆ³n Auth
2.3 Ingresar el request /Sign In
{
"email": "csandoval@tredasolutions.com",
"password": "%AL1h45g6Jw0PChDKKSXRpcFnw"
}
2.4 Obtener response /Sign In
2.5 Ir a la secciĆ³n Authorize
2.6 Ingresar el token
Nota: actualmente el token tiene un tiempo mƔximo a expirar de 1 mes.
2.7 Ir a la secciĆ³n Process
2.8 DescripciĆ³n de parĆ”metros request ProcessCreateFull
ParĆ”metro | DescripciĆ³n | Tipo | Obligatorio |
processTypeId | Tipo de proceso a crear. Toma valores entre 1 y 3.
(Ćnico firmante donde la persona que firma es la persona que se encuentra autenticada)
(MĆnimo dos firmantes donde quienes firman son la persona que se encuentra autenticada y otras personas.)
(Solo firman personas ajenas a quien se encuentra autenticado) | Int | SI |
signatureMethodId | MĆ©todo de firma con el cual se crearĆ” el proceso. Toma como valor 1 o 2.
| Int | SI |
isHandWritten | ParƔmetro que nos permite agregar al caso firma manuscrita:
| Boolean | No |
isPhotographic | ParƔmetro que nos permite agregar al caso firma fotogrƔfica:
| Boolean | No |
deadlineDays | Plazo mĆ”ximo en dĆas para que todos los signatarios firmen el documento asociado al proceso. | Int | SI |
signatures[{...}] | Listado de firmantes vinculados al proceso. Este campo va sujeto a lo indicado en el āprocessTypeIdā. -Si el tipo de proceso es 1 (Solo yo), se debe enviar los datos Ćŗnicamente de la persona autenticada. -Si el tipo de proceso es 2 (Otros y yo), se debe enviar los datos de la persona autenticada, la cual representa el yo y los datos de las demĆ”s personas asociadas hasta un mĆ”ximo de 10, siendo el mĆnimo 2 (incluyendo el yo). -Si el tipo de proceso es 3 (Solo otros), la persona autenticada NO debe hacer parte de este listado y se envĆan los datos de las personas asociadas hasta un mĆ”ximo de 10, siendo el mĆnimo 2
Compuesto por los siguientes parƔmetros: processId, authenticationMethodId, contactInformation. | Array | SI |
processId (parƔmetro del array signatures) | Debe tener como valor 0 | Int | SI |
authenticationMethodId (parĆ”metro del array signatures) | MĆ©todo de autenticaciĆ³n OTP (One-Time Password) con el cual el firmante validarĆ” su proceso de firma. Toma un valor entre 1 y 3
(el cĆ³digo de Ćŗnico uso serĆ” enviado al usuario por medio de una llamada telefĆ³nica al nĆŗmero de celular especificado en el parĆ”metro number)
(el cĆ³digo de Ćŗnico uso serĆ” enviado al usuario por medio de un mensaje de texto al nĆŗmero de celular especificado en el parĆ”metro number)
(el cĆ³digo de Ćŗnico uso serĆ” enviado al usuario al correo electrĆ³nico especificado en el parĆ”metro email) | Int | SI |
contactInformation{} (objeto del array signatures) | Objeto que contiene la informaciĆ³n de contacto del firmante y asociado al proceso a crear.
Compuesto por los siguientes parƔmetros: phone, phoneId, email, personId, person. | Object | SI |
phone{} (objeto de contactInformation) | Objeto que contiene la informaciĆ³n del nĆŗmero de celular asociado al firmante.
Compuesto por los siguientes parƔmetros: indicative, number. | Object | SI |
indicative (parĆ”metro del objeto phone) | Indicativo de paĆs asociado al nĆŗmero de celular del firmante. Ejemplo para Colombia: 57 | String | SI |
number (parĆ”metro del objeto phone) | NĆŗmero celular del firmante. MĆ”ximo de caracteres para Colombia: 10. MĆ”ximo de caracteres para nĆŗmeros extranjeros: 20. | String | SI |
phoneId (parƔmetro de contactInformation) | Debe tener como valor 0. | Int | SI |
(parĆ”metro de contactInformation) | Correo electrĆ³nico del firmante. MĆ”ximo: 100 caracteres | String | SI |
personId (parƔmetro de contactInformation) | Debe tener como valor 0 | Int | SI |
person{} (objeto de contactInformation) | Objeto que contiene informaciĆ³n bĆ”sica asociada al firmante.
Compuesto por los siguientes parƔmetros: firstName, secondName, firstLastName, secondLastName, identification, identificationTypeId, typePersonId | Int | SI |
firstName (parĆ”metro de objeto person) | Primer nombre del firmante. MĆnimo: 2 caracteres MĆ”ximo: 100 caracteres | String | SI |
secondName (parĆ”metro de objeto person) | Segundo nombre del firmante. MĆnimo: 2 caracteres MĆ”ximo: 100 caracteres
En caso de no enviarlo su valor debe ser null. | String | NO |
firstLastName (parĆ”metro de objeto person) | Primer apellido del firmante. MĆnimo: 2 caracteres MĆ”ximo: 100 caracteres | String | SI |
secondLastName (parĆ”metro de objeto person) | Segundo apellido del firmante. MĆnimo: 2 caracteres MĆ”ximo: 100 caracteres
En caso de no enviarlo su valor debe ser null. | String | NO |
identification (parĆ”metro de objeto person) | NĆŗmero de identificaciĆ³n del firmante.
MĆnimo: 5 caracteres MĆ”ximo: 12 caracteres
MĆnimo: 5 caracteres MĆ”ximo: 15 caracteres | String | SI |
identificationTypeId (parĆ”metro de objeto person) | Tipo de identificaciĆ³n del firmante. Toma dos posibles valores:
| Int | SI |
typePersonId (parƔmetro de objeto person) | Tipo de persona del firmante. Toma dos posibles valores:
| Int | SI |
documents[{...}] | Objeto que contiene la informaciĆ³n del documento a firmar.
Compuesto por los siguientes parƔmetros: filename, documentTypeId, base64String.. | Object | SI |
filename (parƔmetro de objeto documents) | Nombre del documento pdf MƔximo: 100 caracteres | String | SI |
documentTypeId (parƔmetro de objeto documents) | Debe tener como valor 1 | Int | SI |
base64String (parƔmetro de objeto documents) | String con el documento pdf codificado en base64 | String | SI |
callback | Es la url donde se debe enviar el documento cuando el proceso se termine (sea firmado exitosamente por todos los involucrados). Esta url es un desarrollo de cada cliente
Este parĆ”metro hace referencia a la estrategia callback mencionada en la secciĆ³n 1.3 | String | NO |
subjectEmail | Asunto que se desea haga parte del correo electrĆ³nico con la solicitud de firma que se envĆa a los firmantes. En caso de no enviarse este parĆ”metro, por defecto el asunto es solicitud de firma. MĆ”ximo: 150 caracteres | String | NO |
messageEmail | Mensaje que se desea haga parte del correo electrĆ³nico con la solicitud de firma que se envĆa a los firmantes. En caso de no enviarse este parĆ”metro, no hay un mensaje por defecto. MĆ”ximo: 500 caracteres | String | NO |
copyEmails | Listado separado por comas de los correos electrĆ³nicos a los cuales se enviarĆ” una copia del documento una vez firmado por todos los involucrados. AquĆ no se ingresa ningĆŗn correo que ya estĆ© asociado a los firmantes. MĆ”ximo string: 255 caracteres MĆ”ximo de correos electrĆ³nicos permitidos: 10 | String | NO |
2.9 Ejecutar el request ProcessCreateFull: Ejemplos
Tipo de proceso āSolo yoā: Ćnico firmante - con firma manuscrita y fotografica
{
"processTypeId": 1,
"signatureMethodId": 2,
"isHandWritten": true,
"isPhotographic": true,
"deadlineDays": 11,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 3,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaseguro",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que la persona que firma en el tipo de proceso āSolo yoā debe ser la misma que estĆ” autenticada en la api.
Tipo de proceso āOtros y yoā: MĆnimo 2 firmantes, mĆ”ximo 10
{
"processTypeId": 2,
"signatureMethodId": 1,
"isHandWritten": false,
"isPhotographic": false,
"deadlineDays": 23,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
},
{
"processId": 0,
"authenticationMethodId": 1,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3114567894"
},
"phoneId": 0,
"email": "juan.perez@email.com",
"personId": 0,
"person": {
"firstName": "Juan",
"secondName": "Manuel",
"firstLastName": "Perez",
"secondLastName": "Ortiz",
"identification": "45784415",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaseguro",
"copyEmails": ""
}
Nota: Recordar que las personas que firman en el tipo de proceso āOtros y yoā debe ser la misma que estĆ” autenticada en la api, quien hace el papel del YO y otras personas ajenas.
Tipo de proceso āSolo Otrosā: MĆnimo 1 firmante, mĆ”ximo 10
{
"processTypeId": 3,
"signatureMethodId": 2,
"isHandWritten": false,
"isPhotographic": false,
"deadlineDays": 5,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaseguro",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que las personas que firman en el tipo de proceso āSolo otrosā son otras personas ajenas a quien se encuentra autenticado.
2.10 Obtener el response ProcessCreateFull
{
"uuid": "string"
}
3. OBTENER DOCUMENTO āESTRATEGIA POLLINGā.
Diagrama de secuencia obtener documento
Nota: el parƔmetro uuid enviado es el retornado en el response de processCreateFull.
3.1 Request Document
curl --location --request GET 'https://demo.firmaseguro.co/api/v1/Document/ByUUID/uuid' \
--header 'Authorization: Bearer Token'
3.2 Response Sign In
{
"documents": [Base64String],
"uuid": "string"
}
4. OBTENER DOCUMENTO āESTRATEGIA CALLBACKā. (RECOMENDADO)
Diagrama de secuencia obtener documento
4.1 Implementar Callback Request Document
Los clientes deben implementar un api rest que contenga un mƩtodo tipo post, y que reciba el siguiente request.
{
"uuid":"string",
"document":"Base64String"
}
MĆ”s informaciĆ³n en la wiki de firma seguro.
Response Sign I
No aplica.
5. CREAR UN PROCESO CON LA V2 DE LA API
5.1 Ir a la parte superior y seleccionar la versiĆ³n 2 de la API
5.2 Ir a la secciĆ³n Process V2
5.3 Ejecutar el request ProcessCreateFull V2:
Para la V2 de la API se necesitarĆ” enviar al tipo de saldo(BalanceTypeId), 1 para saldo por firmas y 2 para saldo por documentos. Es necesario que los firmantes tengan el mismo mĆ©todo de autenticaciĆ³n cuando el tipo de saldo sea por documentos (BalanceTypeId igual a 2), por ejemplo por SMS(2) o Email(3). Nota: el tipo de autenticaciĆ³n por llamada(1) no estĆ” habilitado para saldos por documentos.
Ejemplos
Tipo de proceso āSolo yoā - Saldo por documentos: Ćnico firmante
{
"processTypeId": 1,
"signatureMethodId": 2,
"isHandWritten": false,
"isPhotographic": false,
"deadlineDays": 11,
"balanceTypeId": 2,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 3,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaseguro",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que la persona que firma en el tipo de proceso āSolo yoā debe ser la misma que estĆ” autenticada en la api, y con tipo de saldo por documentos - Email (Todos los firmantes deben de tener el mismo mĆ©todo de autenticaciĆ³n, en este caso de ejemplo, es el Email).
Tipo de proceso āOtros y yoā - Saldo por documentos: MĆnimo 2 firmantes, mĆ”ximo 10
{
"processTypeId": 2,
"signatureMethodId": 1,
"isHandWritten": false,
"isPhotographic": false,
"deadlineDays": 23,
"balanceTypeId": 2,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
},
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3114567894"
},
"phoneId": 0,
"email": "juan.perez@email.com",
"personId": 0,
"person": {
"firstName": "Juan",
"secondName": "Manuel",
"firstLastName": "Perez",
"secondLastName": "Ortiz",
"identification": "45784415",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaseguro",
"copyEmails": ""
}
Nota: Recordar que las personas que firman en el tipo de proceso āOtros y yoā debe ser la misma que estĆ” autenticada en la api, quien hace el papel del YO y otras personas ajenas, ademĆ”s como es con tipo de saldo por documentos - SMS (Todos los firmantes deben de tener el mismo mĆ©todo de autenticaciĆ³n, en este caso SMS).
Tipo de proceso āSolo Otrosā- Saldo por documentos: MĆnimo 1 firmante, mĆ”ximo 10
{
"processTypeId": 3,
"signatureMethodId": 2,
"isHandWritten": false,
"isPhotographic": false,
"balanceTypeId": 2,
"deadlineDays": 5,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaseguro",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que las personas que firman en el tipo de proceso āSolo otrosā son otras personas ajenas a quien se encuentra autenticado, con tipo de saldo por documentos - SMS (Todos los firmantes deben de tener el mismo mĆ©todo de autenticaciĆ³n, en este caso SMS).
5.4 DescripciĆ³n de parĆ”metros request ProcessCreateFull V2
ParĆ”metro | DescripciĆ³n | Tipo | Obligatorio |
balanceTypeId | MĆ©todo de tipo de saldo con el cual se crearĆ” el proceso. Toma como valor 1 o 2.
| Int | SI |