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:
- Generar Token
- /token/crear
- Crear Transacción
- /transacciones/crear
- Adicionar Archivos
- /transacciones/cargar_documento
- Adicionar Firmantes
- /transacciones/registrar_contacto
- Asociar Firmante-Archivos
- /transacciones/vincular
- 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 |
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. 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 |
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
|
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. |
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: |
contactos | Array | Arreglo de datos con formato JSON, con la siguiente estructura: |
firmas | Array | Arreglo de datos con formato JSON, con la siguiente estructura: |
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:
|
sort | No | String | Permite ordenar los resultados de acuerdo a la siguiente estructura:
|
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 |
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