2. PRESENTACIÓN


En este documento se pretende establecer los lineamientos para la integración de la plataforma SIGNIO con otros sistemas.



3. DEFINICIÓN DE PROTOCOLOS DE COMUNICACIÓN


Es importante tener en cuenta que el servicio API de SIGNIO está estructurado mediante arquitectura RESTFULL y su proceso de comunicación de datos será a través de JSON.



4. EJEMPLO DE CÓMO CREAR UNA TRANSACCIÓN SENCILLA


Para crear una transacción básica mediante el consumo de API, se debe consumir los servicios mencionados a continuación en el orden que se indica en los siguientes pasos:


  1. Generar Token
    • /token/crear
  2. Crear Transacción
    • /transacciones/crear
  3. Adicionar Archivos
    • /transacciones/cargar_documento
  4. Adicionar Firmantes
    • /transacciones/registrar_contacto
  5. Asociar Firmante-Archivos
    • /transacciones/vincular
  6. Distribuir
    • /transacciones/distribuir



5. SERVICIOS INCLUIDOS


Los servicios incluidos en esta API son los siguientes:

  • Generar Token
  • Listar Transacciones
  • Listar Tags
  • Listar Transacciones Base
  • Registrar Transacción
  • Carga Documentos
  • Registra Firmantes
  • Vincular Documentos Firmantes
  • Cambiar Orden Distribución
  • Distribuir Transacción
  • Gestionar Transacción
  • Devolver Transacción
  • Eliminar Transacción
  • Generar URL onPremise



6. DEFINICIÓN DE LOS SERVICIOS INCLUIDOS


6.1 Generar Token


El servicio de generar token permite crear un token de autenticación para el consumo de servicios presentes en este documento




Parámetros


Campo

  Requerido

Tipo

Descripción

email

  Si

String

Corresponde a la dirección de correo electrónico con la que se registró el usuario en el sistema.

password

  Si

String

Deberá ser la cadena de caracteres establecida como contraseña para el ingreso del usuario.



Respuesta


Campo

Tipo

Descripción

token

String

Cadena de caracteres, que permiten la conexión a los servicios

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno)

mensaje

String

Corresponde al mensaje de respuesta de la operación.



El código retornado debe enviarse como parámetro


Authorization: Bearer {Token enviado}



EJEMPLO SOLICIUD PHP


EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.2 Listas transacciones


El servicio de Listar transacciones permitirá obtener la lista de todas las transacciones realizadas por el cliente en la plataforma




Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN



Parámetros


Campo

Requerido

Tipo

Descripción

estado

   No

Integer

Será un indicador que permitirá al sistema saber que transacciones listar según el estado de estas (0: Todos los estados, 1: Transacciones en Elaboración, 2: Transacciones Pendientes de Firma, 3: Transacciones Firmadas, 4: Transacciones Rechazadas, 6: Transacciones Suspendidas, 7: Transacciones en Captura de Datos)



Respuesta


Campo

Tipo

Descripción

transacciones

Array

Corresponde a un arreglo de datos con estructura JSON

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno)

mensaje

String

Corresponde al mensaje de respuesta de la operación.





EJEMPLO DE SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.3 Listar TAGS / Etiquetas


El servicio de Listar TAGS permitirá obtener la lista de todas las etiquetas con las cuales se puede clasificar u organizar una transacción a manera de etiqueta "TAG".



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN



Parámetros


Campo

Tipo

Descripción

No requeridos



Respuesta


Campo

Tipo

Descripción

tags

Array

Corresponde a un arreglo de datos

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno)

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.4 Listar Transacciones Base


El servicio de Listar transacciones Base permitirá obtener la lista de todas las transacciones base / maestras creadas previamente por el cliente.




Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN



Parámetros


Campo

Tipo

Descripción

No requeridos



Respuesta


Campo

Tipo

Descripción

transacciones

Array

Corresponde a un arreglo de datos con estructura JSON

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno)

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.5 Registrar transacción


El servicio Registrar Transacción permite crear un transacción



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros

Campo

      Requerido

Tipo

Descripción

nombre

  Si

String

Cadena de máximo 255 caracteres del nombre con el que se registrará la transacción.

mensaje

  No

String

Corresponde a un mensaje asociado a la transacción

ciclo_aprobacion

  No

Integer

Digito numérico que indica si la transacción incluirá o no firmantes aprobadores. (0: No incluye aprobadores, 1: Incluye aprobadores).

tags

  No

Array

Arreglo de tipo cadena con las clasificaciones en las cuales se ha asociado la transacción, la lista de tags se obtiene mediante el servicio Listar Tags de la API, se pueden enviar diferentes tags separados por el carácter punto y coma “;”.

id_transaccion_base

  No

String

Si se desea hacer uso de una transacción base / maestra y copiar su estructura, es necesario indicar el id de la transacción que se desea copiar, esta información se obtiene desde el servicio Listar Transacciones Base.

external_id

  No

String

Opcional, Id interno de la aplicación que genera la transacción, se puede utilizar en los webhooks de respuesta

cc

  No

String

Opcional, listado de correos separados por coma (,) los cuales serán notificados una vez finalice el sobre o transacción, estas personas podrán consultar todos los documentos.

op_btnRechazo

  No

Integer

Opcional, Digito numérico que indica si se mostrará la opción de rechazo al momento de firmar. (0: No permite rechazo, 1: Permite rechazo).

op_foto

  No

String

Opcional, Indica la obligatoriedad de la foto al momento de realizar la firma.
 NO: No se solicitar[a la toma de foto

OP: La toma de foto es opcional

OB: La toma de foto es obligatoria 

op_certLegops

  No

Integer

Opcional, Digito numérico que indica si se agregará la certificación de Legops en los documentos. (0: No se agrega la certificación, 1: Se agrega la certificación).

op_firmasProcesadas

  No

Integer

Opcional, Digito numérico que indica si se permite ver el historial de firmas procesadas a firmantes o aprobadores. (0: No visible, 1: Visible).

remitente

  No

String

Opcional, Indica el remitente que se mostrará en el cuerpo del correo enviado.

 

mensaje_firma

  No

String

Opcional, Indica el mensaje que será mostrado a firmantes y aprobadores en el primer paso del proceso de firma.

 

mensaje_final

  No

String

Opcional, Indica el mensaje que será mostrado a firmantes y aprobadores en el último paso del proceso de firma.

permiteEdicion

  No

Integer

Opcional, Digito numérico que indica si el sobre puede ser devuelto con observaciones por aprobadores. (0: No se agrega la certificación, 1: Se agrega la certificación).

permiteEdicionFirmantes

  No

Integer

Opcional, Digito numérico que indica si el sobre puede ser devuelto con observaciones por firmantes. (0: No se agrega la certificación, 1: Se agrega la certificación).

on_premise_signature

  No

Bool

Opcional, Digito numérico que indica si los contactos pueden realizar la firma en sitio. (0: No se permite, 1: Se permite)

envelopeDeduplicationKey

  No

String

Máximo 36 caracteres, permite crear sobres duplicados para un mismo proceso. De ser generada por el sistema cliente.

notificar_contacto

  No

String

Opcional digito numérico que indica que el sobre contiene notificados (0: No se permite, 1: Se permite)

campos_plantillas

  No

Json

Opcional, Con este campo se completaran los valores de las plantillas, la llave o “key” debe ser igual al nombre del input a llenar en la plantilla en Signio.

{

    "name""",

    "identification"""

}

created_by

  No

String

Opcional, Con este campo se puede indicar que usuario será asignado como “distribuidor”, este recibirá las notificaciones respectivas.


Respuesta


Campo

Tipo

Descripción

id_transaccion

String

Corresponde al id de la transacción creada, será 0 si la operación no se pudo realizar. Cadena de 36 caracteres.

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable).

mensaje

String

Corresponde al mensaje de respuesta de la operación.

errores

Json

Arreglo de errores generados al procesar la solicitud.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICIUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.6 Cargar documentos



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

id_transaccion

  Si

String

Id de la transacción a la cual se le desea cargar el documento

documento

  Si

File

Archivo a cargar, las extensiones o tipos de archivos permitidos son: doc, docx, xls, xlsx, png, jpg y pdf

metatags

  No

Json

Información adicional para el posicionamiento de la estampa y asignación de roles. La estructura debe indicar el rol con los tags requeridos (MANUAL FORMATO ETIQUETAS DOCUMENTOS)

{

  "rol": {

    "SigIDType""",

    "SigID"""

  }

}



Respuesta


Campo

Tipo

Descripción

id_documento

String

Corresponde al id del documento cargado, será 0 si la operación no se pudo realizar. Esto es una cadena de 200 caracteres.

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.7 Registrar Firmantes para Firmar Transacción




Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN



Parámetros

Campo

      Requerido

Tipo

Descripción

id_transaccion

  Si

String

Id de la transacción a la cual se le desea cargar el documento

nombre

  Si

String

Cadena de máximo 50 caracteres que referencian el nombre del firmante de la transacción.

tipo_identificacion

  Si

Char(3)

Cadena de 3 caracteres con los siguientes valores:

CC: Cedula de Ciudadanía.

CD: Carnet Diplomático.

CE: Cedula de extranjería.

OT: Otro.

PP: Permiso Especial de Permanencia.

PS: Pasaporte.

TI: Tarjeta de Identidad.

VI: Visa.

identificacion

  Si

String

Cadena de máximo 20 caracteres que referencian el número de identificación

email

  Si

String

Cadena de máximo 50 caracteres que referencian el correo electrónico del firmante.

orden

  No

Integer

Orden en el cual esta persona firmará/aprobará en esta transacción

aprobador

  No

Bool

Digito numérico que indica si el firmante es de tipo aprobador o no. (0: Firmante no Aprobador, 1: Firmante Aprobador).

tipo_firma

  No

Bool

Digito numérico que indica si la firma es electrónica y digital (1: Firma Digital, 0: Firma Electrónica)

tipo_firmante

  No

Bool

Digito numérico que indica el tipo de firmante, (1: Persona Natural, 0: Persona Jurídica)

celular

  No

String

Cadena de máximo 15 caracteres que referencian el número de celular de contacto

razonsocial

  No

String

Cadena de máximo 45 caracteres que referencian el nombre de la empresa la cual representa legalmente

company_identification_type

  No

String

Cadena de máximo 5 caracteres que referencian el tipo de identificación de la empresa la cual representa legalmente

company_identification

  No

String

Cadena de máximo 30 caracteres que referencian el número de identificación de la empresa la cual representa legalmente

servicio_identidad

  No

String

Valores permitidos: basic, experian, experian_lite

rol

  No

String

Valores permitidos: Notificado

states

  No

Array

Arreglo de enteros que indica en que estados se notificará a los contactos con rol Notificado, estados permitidos:

3 – FIRMADA

4 – RECHAZADA

6 - SUSPENDIDA

8 – DEVOLUCIÓN CON OBSERVACIONES

enable_comments

  No

Bool

Tipo de dato lógico, indica si el firmante / aprobador tiene habilitada la opción de agregar un comentario al momento de realizar el proceso de firma.

on_premise_signature

  No

Bool

Digito numérico que indica si el contacto puede realizar la firma en sitio. (0: No se permite, 1: Se permite

  • Al omitirse se tomará el valor establecido en el sobre.
  • Es necesario que tanto el sobre como el contacto estén habilitados para realizar la firma en sitio. 

Operation_rol

 No

String

Arreglo de cadenas separado por comas, donde cada cadena debe ser el rol asignado en el documento para cada firmante. Esto aplica únicamente para documentos que usen metatags. 

Ejemplo: {{SigStamp:signer1:250,55}} donde el operation_rol es signer1


RESPUESTA


Campo

Tipo

Descripción

id_firmante

String

Corresponde al id cifrado del firmante creado / agregado, será 0 si la operación no se pudo realizar. Esto es una cadena de 200 caracteres.

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.8 Vincular Firmantes a Documentos


El Servicio de Vincular permite asociar firmantes a documentos.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

id_transaccion

  Si

String

Id de la transacción a la cual se le desea cargar el documento.

id_firmante

  Si

String

Id del firmante que se asociara. Valor retornado por adicionar contacto.

id_documento

  Si

String

Id del documento que se asociara. Valor retornado por adicionar archivo.

posicion

  No

Json

Posición de firma (estampa) en el documento. Debe poseer la siguiente estructura:

 

{

    "pagina"1// Número de página

    "alto"0// Valor en pixeles

    "ancho"0// Valor en pixeles

    "x"0// Coordenadas tipo canvas[a1] 

    "y": 0 // Coordenadas tipo canvas

}

attachment

 No

Bool

Indica el tipo de vinculación entre el documento y el firmante, si es considerado como adjunto, no es necesario definir la posición de firma.  (1: Adjunto 0: Firma)

stamps

 No

Array<Json>

Arreglo de posiciones de estampas en el documento. Debe poseer la estructura indicada para el campo “posición”. 

operation_rol

No

String

Cadena de texto que indica el rol que tendrá el usuario en la operación y/o plantillas.

 [a1]

 



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA



EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.8 Cambiar orden de Distribución


Este servicio permitirá cambiar el orden de distribución de la transacción para el proceso de firma. 


Existen dos tipos de distribución: distribución en paralelo, que enviará la transacción a todos los firmantes al mismo tiempo para que sean firmados los documentos correspondientes.


Por otro lado está la distribución en serie, en la cual se define el orden de distribución y, una vez distribuida la transacción para su firma, se enviará el correo a cada uno de los firmantes en el orden establecido, una vez cada firmante haya firmado todos los documentos que le corresponden.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

id_transaccion

  Si

String

Identificador de la transacción, corresponde al ID de la transacción.

id_firmante

  Si

String

Identificador del firmante al cual se desea cambiar el orden.

orden

  Si

Integer

Nueva posición de envío.



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.10 Distribuir la Transacción


Este servicio permite enviar la transacción para su proceso de firma



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

id_transaccion

  Si

String

Identificador de la transacción, corresponde al ID de la transacción.



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.11 Obtener Transacción


Este servicio permite obtener toda la información relacionada con la transacción (Datos de la transacción, Documentos, Firmantes y su correspondiente Asociación).



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

id_transaccion

  Si

String

Identificador de la transacción, corresponde al ID de la transacción.



Respuesta


Campo

Tipo

Descripción

id_transaccion

String

Identificador de la transacción, corresponde al ID de la transacción.

nombre

String

Cadena de máximo 255 caracteres con el que se registró  la transacción.

mensaje

String

Cadena de 3 caracteres con los siguientes valores (CC: Cedula de Ciudadanía, CE: Cedula de extranjería, NIT: NIT de la empresa, PS: Pasaporte).

ciclo_aprobacion

Bool

Digito numérico que indica si la transacción incluirá o no firmantes aprobadores. (0: No incluye aprobadores, 1: Incluye aprobadores).

documentos

Array

Arreglo de datos con formato JSON, con la siguiente estructura:

{
"id_documento": "Identificador del documento cargado",
"nombre": "Nombre del archivo",
"path": "Ruta pública del archivo"
 }

contactos

Array

Arreglo de datos con formato JSON, con la siguiente estructura:

{
"id_contacto": "Identificador del firmante / aprobador agregado",
"tipo_identificacion": "Cadena de 3 caracteres con los siguientes valores (CC: Cedula de Ciudadanía, CE: Cedula de extranjería, NIT: NIT de la empresa, PS: Pasaporte).",
"identificacion": "Cadena de máximo 20 caracteres que referencian el número de identificación ",
"nombre": "Cadena de máximo 50 caracteres que referencian el nombre del firmante de la transacción.",
"email": "Cadena de máximo 50 caracteres que referencian el correo electrónico del firmante.",
"orden": "Orden en el cual esta persona firmará/aprobará en esta transacción ",
"tipo_firma": "Digito numérico que indica si la firma es electrónica y digital (1: Firma Digital, 0: Firma Electrónica)",
"aprobador": "Digito numérico que indica si el contacto realizará el rol de aprobador",
   "enable_comments": "
 Tipo de dato lógico, indica si el firmante / aprobador tiene habilitada la opción de agregar un comentario al momento de realizar el proceso de firma",
 }

firmas

Array

Arreglo de datos con formato JSON, con la siguiente estructura:

{
"id_firmante": "Identificador del firmante / aprobador agregado",
"id_documento": "identificador del documento cargado",
"aprobador": "Digito que india que si este registro indica si se realizó una aprobación al documento",
" fecha_firma ": "fecha en la cual se realizó la firma / aprobación",
 }

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.





EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.12 Devolver Transacción


Este servicio permite devolver una transacción. Cabe resaltar que sólo aquellas que se encuentren en estado "pendiente de firma" y "Captura de datos" pueden ser retornadas a estado "En elaboración".


Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

id_transaccion

  Si

String

Identificador de la transacción, corresponde al ID de la transacción.



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 06: recurso no encontrado).

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




SOLICITUD EJEMPLO ASP.NET




EJEMPLO RESPUESTA




6.13 Eliminar Transacción


Este servicio permite eliminar una transacción. Cabe resaltar que sólo aquellas que se encuentren en estado "En elaboración" pueden ser eliminadas.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

Tipo

Descripción

id_transaccion

String

Identificador de la transacción, corresponde al ID de la transacción.



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 06: recurso no encontrado).

mensaje
String
Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.14 Proteger documento


Este servicio permite marcar / desmarcar un documento como "protegido". Cuando el sobre se haya firmando completamente, los documentos protegidos no pueden ser consultados o descargados.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

Tipo

Descripción

id_documento

String

Identificador del documento, corresponde al ID del documento.

protect

Bool

Indica si el documento se marca o desmarca como “protegido”:

 

TRUE: Marca el documento como protegido

FALSE: Desmarca el documento como protegido



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 05: contenido no procesable, 06: recurso no encontrado).

mensaje

Bool

Corresponde al mensaje de respuesta de la operación




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.15 Listar campos Plantillas


Este servicio permite obtener el arreglo de inputs o campos a llenar en los documentos plantilla que pertenecen a un sobre.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

Tipo

Descripción

id_transaccion

String

Identificador de la transacción, corresponde al ID de la transacción.



Respuesta


Campo

Tipo

Descripción

codigo

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno, 06: recurso no encontrado).

campos

Array

Corresponde a un arreglo de datos con estructura JSON

mensaje

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.16 Buscar sobres


Este servicio permite filtrar por diferentes parámetros. Se listarán un máximo de mil (1000) sobres.




Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

filter[name]

  No

String

Permite filtrar por el nombre del sobre, se buscará la cadena indicada en el nombre sin importar mayúsculas o minúsculas.

filter[from]

  No

Datetime

Permite filtrar los resultados por el campo “updated_at”, se listaran los registros cuya fecha de actualización sea mayor o igual al valor indicado.

filter[to]

  No

Datetime

Permite filtrar los resultados por el campo “updated_at”, se listaran los registros cuya fecha de actualización sea menor o igual al valor indicado.

filter[status]

  No

String

Permite filtrar los resultados por el estado actual del sobre, los valores permitidos son:

  • En Proceso
  • Pendiente de Firma
  • Firmada
  • Rechazada
  • Suspendida

sort

  No

String

Permite ordenar los resultados de acuerdo a la siguiente estructura:
 

  • -name= Ordena por nombre del sobre de manera descendente.
  • +name= Ordena por nombre del sobre de manera ascendente.
  • -status= Ordena por estado del sobre de manera descendente.
  • +status= Ordena por estado del sobre de manera ascendente.
  • -created_at= Ordena por fecha de creación de manera descendente.
  • +created_at= Ordena por fecha de creación de manera ascendente.
  • -updated_at= Ordena por fecha de actualización de manera ascendente.
  • +updated_at= Ordena por fecha de creación de manera ascendente.

offset

  No

Integer

Especifica el desplazamiento de la primera fila que se devolverá. Debe ser un valor numérico no negativo.



Respuesta


Campo

Tipo

Descripción

envelopes

Array

Corresponde a un arreglo de datos con estructura JSON

envelopes[][id]

String

Identificador del sobre, corresponde al ID del sobre.

envelopes[][name]

String

Cadena de máximo 100 caracteres con el que se registró el sobre.

envelopes[][status]

String

Descripción del estado actual del sobre en el sistema.

envelopes[][created_at]

Datetime

Fecha de registro del sobre en el sistema con zona horaria UTC +00:00

envelopes[][updated_at]

Datetime

Ultima fecha de actualización o modificación den sobre con zona horaria UTC +00:00

envelopes[][documents_count]

Integer

Cantidad de documentos relacionados en el sobre.

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

message

String

Corresponde al mensaje de respuesta de la operación.





EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.17 Listar Plantillas

Este servicio permite obtener las plantillas de documentos creadas en el sistema.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Respuesta


Campo

Tipo

Descripción

templates

Array

Corresponde a un arreglo de datos con estructura JSON

templates[][id]

Integer

Identificador de plantilla, corresponde al ID de la plantilla.

templates[][name]

String

Cadena de máximo 100 caracteres con el que se registró la plantilla.

templates[][description]

String

Cadena de texto de descripción de la plantilla

templates[][type]

String

Identificador del tipo de plantilla, posibles valores:

PLL: Formato documento

XFORM: Formato PDF forms.

templates[][status]

Integer

Estado actual de la plantilla en el sistema, posibles valores:

1 = Activa

2 = Inactiva

templates[][protected]

Boolean

Identificador de protección de la plantilla, al ser verdadero generará un título valor electrónico.

templates[][roles]

String

Listado de roles separados por coma asignados a la plantilla.

templates[][created_at]

Datetime

Fecha de registro del sobre en el sistema con zona horaria UTC +00:00

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

message

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.18 Usar Plantilla


Este servicio permite agregar una plantilla a una sobre creado en el sistema, generando un documento que será asignado por defecto como "Adjunto" a todos los contactos presentes en el sobre



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

Tipo

Descripción

envelope_id

String

Identificador del sobre, corresponde al ID del sobre al cual se desea agregar la plantilla, debe ser especificado en la url de la petición.

template_id

Integer

Identificador de plantilla, corresponde al ID de la plantilla que se desea agregar al sobre, debe ser especificado en el cuerpo de la petición.

fields

Json

Opcional, Con este campo se completaran los valores de las plantillas, la llave o “key” debe ser igual al nombre del input a llenar en la plantilla en Signio.

{

    "name""",

    "identification"""

}



Respuesta


Campo

Tipo

Descripción

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

document

Object

Corresponde al documento creado a partir de la plantilla asignada al sobre.

message

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.19 Actualizar Valores Plantilla


Este servicio permite actualizar los valores o campos presentes en un sobre creado en el sistema.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

Tipo

Descripción

envelope_id

String

Identificador del sobre, corresponde al ID del sobre al cual se desea agregar la plantilla, debe ser especificado en la url de la petición.

document_id

String

Identificador del documento tipo plantilla, corresponde al ID del documento que se desea actualizar, debe ser especificado en la url de la petición.

fields

Json

Opcional, Con este campo se completaran los valores de las plantillas, la llave o “key” debe ser igual al nombre del input a llenar en la plantilla en Signio.

{

    "name""",

    "identification"""

}



Respuesta


Campo

Tipo

Descripción

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

document

Object

Corresponde al documento creado a partir de la plantilla asignada al sobre.

message

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA





6.20 Obtener Link


Este servicio permite generar un enlace de edición si el sobre se encuentra en estado "En elaboración", de lo contrario permitirá consultar el sobre. Este enlace realizará automáticamente el login en el sistema con el usuario que lo solicite. Posee una duración de treinta (30) minutos.



Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Respuesta


Campo

Tipo

Descripción

magic_link

String

Enlace de consulta del sobre con una duración x, al acceder a este link se iniciara sesión con el usuario que lo solicitó. 

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

message

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA




6.21 Autenticación


El servicio genera un arreglo de tokens  por cada tenant en donde el usuario tenga acceso.


Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 


Parámetros


Campo

  Requerido

Tipo

Descripción

email

  Si

String

Corresponde a la dirección de correo electrónico con la que se registró el usuario en el sistema.

password

  Si

String

Deberá ser la cadena de caracteres establecida como contraseña para el ingreso del usuario.

ttl

  No

Integer

Indica el tiempo de vida en minutos de los tokens a generar, en valor por defecto son 120 minutos. 



Respuesta


Campo

Tipo

Descripción

tokens

Array

Corresponde a un arreglo de datos con estructura JSON.

tokens[][token]

String

Cadena de caracteres, que permiten la conexión a los servicios, la cadena retornada debe usarse  como cabera de autenticación tipo Bearer.

tokens[][tenant]

String

Indica el tenant o cliente al que corresponde el token generado y al cual tiene acceso.

tokens[][expires_at]

Datetime

Fecha de expiración del token con zona horaria UTC +00:00

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 02: usuario inactivo, 03: cliente inactivo, 04: error interno)

message

String

Corresponde al mensaje de respuesta de la operación.




EJEMPLO SOLICITUD PHP




EJEMPLO SOLICITUD JAVA




EJEMPLO SOLICITUD ASP.NET




EJEMPLO RESPUESTA





6.22 CARGAR TVE


Este servicio permite cargar un Pagaré (TVE).


Header


Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 

Parámetros


Campo

      Requerido

Tipo

Descripción

type

  Si

String

Tipo de pagaré que se desea generar (BLANK, SIMPLE)

template_id

  Si

String

Id del template en TVE. Si se trata de un documento externo que se va a cargar se debe configurar este valor en cero template_id=0

reference

  No

String

Una referencia que facilite la identificación y búsqueda del pagaré. Opcional

expiration

 Requerido para type SIMPLE

Date

Fecha de vencimiento del pagaré. obligatorio para pagaré tipo SIMPLE

amount

Requerido para type SIMPLE

Integer

Valor del pagaré, obligatorio para pagaré tipo SIMPLE

payment_way

Requerido para type SIMPLE

String

Forma de pago, obligatorio para pagaré tipo SIMPLE

payment_place

Requerido para type SIMPLE

String

Lugar de pago, obligatorio para pagaré tipo SIMPLE

document

Requerido si template=0

File

Documento en PDF del pagaré que se quiere custodiar.

consecutive

Requerido si template=0

String

Consecutivo del pagaré.


Respuesta


Campo

Tipo

Descripción

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

document_id

String

Corresponde al documento creado a partir de la plantilla asignada al sobre.

message

String

Corresponde al mensaje de respuesta de la operación.



EJEMPLO SOLICITUD EN PHP



EJEMPLO SOLICITUD EN JAVA



 

EJEMPLO SOLICITUD ASP.NET

 


EJEMPLO RESPUESTA



6.23 EDITAR TVE


Este servicio permite editar un Pagaré (TVE).


PUT

 envelopes/:envelope_id/tve/:documento_id



Header

Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 

Parámetros

Campo

      Requerido

Tipo

Descripción

type

  Si

String

Tipo de pagaré que se desea generar (BLANK, SIMPLE)

reference

  No

String

Una referencia que facilite la identificación y búsqueda del pagaré. Opcional

expiration

 Requerido para type SIMPLE

Date

Fecha de vencimiento del pagaré. obligatorio para pagaré tipo SIMPLE

amount

Requerido para type SIMPLE

Integer

Valor del pagaré, obligatorio para pagaré tipo SIMPLE

payment_way

Requerido para type SIMPLE

String

Forma de pago, obligatorio para pagaré tipo SIMPLE

payment_place

Requerido para type SIMPLE

String

Lugar de pago, obligatorio para pagaré tipo SIMPLE


Respuesta


Campo

Tipo

Descripción

code

String

Corresponde al código de respuesta de la operación (00: Operación correcta, 01: token invalido, 02: usuario inactivo, 03: cliente inactivo, 04: error interno).

document_id

String

Corresponde al documento creado a partir de la plantilla asignada al sobre.

message

String

Corresponde al mensaje de respuesta de la operación.



EJEMPLO SOLICITUD EN PHP


EJEMPLO SOLICITUD JAVA



EJEMPLO SOLICITUD ASP.NET



EJEMPLO RESPUESTA





6.24 Generar URL para proceso de firma 


Genera url firmada para realizar el proceso de firma con token en pantalla u opciones de envío (SMS/EMAIL).


PUT

envelope/onpremise/get-signed-url


Header

Authorization: Bearer {token} donde {token} es el código retornado por GENERAR TOKEN

 

Parámetros

Campo

      Requerido

Tipo

Descripción

document_type

Si

String

Tipo de identificación (e.j CC)

document

Si

String

Número de identificación

transaction_id

Si

String

UUID del sobre / transacción

direct_signature

No

Boolean

0: Direcciona a la vista de sobres (mostrando únicamente el sobre en cuestión de transaction_id); 

1: Direcciona al proceso de firma del sobre enviado en la transaction_id

op_token

No

String

SCREEN: mostrará el token en pantalla.

SHOW_OPTIONS: mostrará las opciones de envío de token (sms/email).

confirmation_url

No

String

Url a la que será redireccionado una vez se termine el proceso de firma.


Respuesta


Campo

Tipo

Descripción

url

String

Corresponde a la ruta firmada, válida para firma en sitio.



EJEMPLO SOLICITUD EN PHP


EJEMPLO SOLICITUD JAVA


EJEMPLO SOLICITUD ASP.NET



EJEMPLO RESPUESTA