Firma Seguro API (VersiĆ³n anterior)

Owned by Firma Seguro
Last updated: Sept 13, 2023
10 min read

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.

 

 

  1. 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.

  1. 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