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. Solo Yo: 1 (Único firmante donde la persona que firma es la persona que se encuentra autenticada) Otros y yo: 2 (Mínimo dos firmantes donde quienes firman son la persona que se encuentra autenticada y otras personas.) Solo Otros: 3 (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. Firma electrónica simple: 1 Firma electrónica certificada: 2	Int	SI
isHandWritten	Parámetro que nos permite agregar al caso firma manuscrita: "isHandWritten": true, (El proceso tendrá firma manuscrita) "isHandWritten": false, (El proceso no tendrá firma manuscrita)	Boolean	No
isPhotographic	Parámetro que nos permite agregar al caso firma fotográfica: "isPhotographic": true, (El proceso tendrá firma fotográfica) "isPhotographic": false, (El proceso no tendrá 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 OTP Llamada: 1 (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) OTP SMS: 2 (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) OTP Email: 3 (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
email (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. Cédula de Ciudadanía: Mínimo: 5 caracteres Máximo: 12 caracteres Cédula Extranjera: 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: Cédula de Ciudadanía: 1 Cédula Extranjera: 2	Int	SI
typePersonId (parámetro de objeto person)	Tipo de persona del firmante. Toma dos posibles valores: Persona Natural: 1 Persona Juridica: 2	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.

Saldo por firmas: 1
Saldo por documentos: 2

Int

SI

FirmaSeguro

Firma Seguro API (Versión anterior)

VERSIONAMIENTO DEL DOCUMENTO

APROBACIONES DEL DOCUMENTO