Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

 

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

 

DOCUMENTACIÓN SERVICIO WEB FIRMA ELECTRÓNICA

 

Este documento establece la definición de los métodos y los valores establecidos como parámetros para el consumo del aplicativo Firma Electrónica 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 electrónica 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 electrónica 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 electrónica API responderá cuando el proceso esté terminado exitosamente.

 

  1. CREAR UN PROCESO.

 

Diagrama de secuencia “Creación de proceso”

 

2.1 Ir a la URL de la API suministrada

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 Ejecutar el request ProcessCreateFull: Ejemplos

 

Tipo de proceso “Solo yo”: Único firmante

{

    "processTypeId": 1,

    "signatureMethodId": 2,

    "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 firmaelectrónica",

    "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,

    "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 firmaelectrónica",

    "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,

    "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 firmaelectronica",

    "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.9 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

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.10 Obtener el response ProcessCreateFull

{                                     

  "uuid": "string"     

}   

 

  1. 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://{dominio-api-entorno}/api/v1/Document/ByUUID/uuid' \

--header 'Authorization: Bearer Token'

                           

3.2 Response Sign In

 

{

    "documents": [Base64String],

    "uuid": "string"

}

 

  1. 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 dirigirse a los procesos detallados en la wiki

 

                           Response Sign I

No aplica.

 

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

    "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 firmaelectrónica",

    "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,

    "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 firmaelectrónica",

    "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,

    "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 firmaelectrónica",

    "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