Manual De Usuario API Mis Pagarés

1. OBJETIVO

Este documento tiene como objetivo guiarte en el uso del API de Mis Pagarés.

2. INTRODUCCIÓN

Este documento está aquí para hacerte la vida más sencilla al interactuar con la plataforma Mis Pagarés y los servicios de OLIMPIA IT. Estamos aquí para echarte una mano con la solicitud de validación de datos del cliente usando el servicio ANI, la aprobación del tratamiento de datos públicos ATDP, el proceso de validación, la firma de PAGARÉS y la recepción de archivos en formato pdf. Además, aquí encontrarás los contratos de servicio que se aplican a este proceso.

3. DESCRIPCIÓN DEL PROCESO MIS PAGARÉS

3.1. Consumo API Mis Pagarés

Se realiza la conexión por medio del navegador, con la URL Mis Pagarés – API – Swagger UI (olimpiait.com). Aquí se tendrá acceso a los diferentes métodos GET y POST del API.

3.2. Autenticación

3.2.1. Inicio de sesión

Este servicio te da la bienvenida para que puedas solicitar de manera segura cada uno de los servicios que ofrece el API.

3.2.1.1. Operación

Método HTTP	Nombre operación	Descripción
POST	/autenticacion	Establece la seguridad de consumo para las diferentes operaciones del API.

3.2.1.2. Estructura modelo de consulta

Nombre	Ubicación	Descripción	Requerido
Usuario	Body	Usuario para acceso al API.	Si
Contraseña	Body	Contraseña para acceso al API.	Si
Identificador	Body	Código de aplicación único para cada comercio.	Si

3.2.1.3. Petición

{
  "Usuario": "Usuario asignado",
  "Contrasena": "Contraseña",
  "Identificador": "45ed5aa4-91e3-412b-855a-01ed2467a554"
}

3.2.1.4. Respuesta

Aquí te mostramos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
Errada:

3.3. Proceso general

3.3.1. Iniciar

Este servicio te ayuda a crear el proceso para firmar el pagaré. Solo necesitas enviar los datos del deudor para registrarlo en el sistema junto con el idProcesoCliente, que es único para cada cliente. Este idProcesoCliente se puede generar automáticamente o ajustarse a tus parámetros.

3.3.1.1. Operación

Método HTTP	Nombre operación	Descripción
POST	/iniciar	Registra un proceso nuevo. En caso de no recibir un proceso identificador por parte del cliente se genera uno de forma automática.

3.3.1.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
identificacionComercio	int	Body	Identificación del comercio.	Si
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	Si
nombres	String	Body	Nombre del solicitante del crédito.	Si
apelldos	String	Body	Nombre del solicitante del crédito.	Si
celular	String	Body	Teléfono del solicitante dl crédito.	Si
correo	String	Body	Correo electrónico del solicitante del crédito.	Si
numeroIdentificacion	String	Body	Número de identificación del solicitante del crédito.	Si
tipoIdentificacion	int	Body	Código del tipo de identificación. Información suministrada al cliente. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	Si
idTipoEndoso	int	Body	Código para identificar el tipo de endoso. Se puede usar el valor por defecto 0; o los siguientes códigos: En propiedad con Responsabilidad. En propiedad sin Responsabilidad. En Garantía. En Procuración.	Si
tipoProducto	String	Body	Campo opcional que se puede usar para identificar el producto. Por ejemplo: crédito 1, tarjeta de crédito	Opcional

3.3.1.3. Petición

{
    "identificacionComercio": "90000000-1",
    "idProcesoClienteExterno": "",
    "nombres": "Un Nombre",
    "apellidos": "Un Apellido",
    "celular": "319....",
    "correo": "micorreo@micorreo.com",
    "identificacion": "112324345",
    "tipoIdentificacion": 104,
    "idTipoEndoso": 0,
   "tipoProducto": “Un tipo de producto”,
}

3.3.1.4. Respuesta

Aquí te mostramos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
Errada:

3.3.1.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
idProcesoClienteExterno	String	Body	Código de proceso único generado para el proceso.
mensaje	String	Body	Mensaje de confirmación de la transacción.

3.3.2. Proceso estado pagaré

Con este servicio, puedes revisar fácilmente cómo va tu pagaré y su último endoso. Para obtener la información, solo necesitas usar el Serial o el IdProcesoCliente. ¡Tranquilo! Solo necesitas ingresar uno de estos parámetros.

3.3.2.1. Operación

Método HTTP	Nombre operación	Descripción
Get	/pagare	Muestra el estado de pagaré

3.3.2.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
Serial	Guid	Body	Serial de proceso, es único para cada solicitud realizada al servicio.	Opcional (Mínimo uno)
IdProcesoClienteExterno	String	Body	Código de proceso, es único para cada solicitud realizada al servicio.	Opcional (Mínimo uno)

Consulta:

Manual_01_MIS PAGARES_12

3.3.2.3. Respuesta

Aquí te mostramos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
No exitosa:
No se encuentra la información enviada:

3.3.2.4. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
IdProcesoClienteExterno	Guid	Body	Código único generado para el proceso.
serialPagare	String	Body	Serial del pagaré.
estadoPagare	String	Body	Estado del pagaré.
empresaActualId	String	Body	Id de la empresa actual, que es dueña del pagaré.
empresaActualNombre	String	Body	Nombre de la empresa actual, que es dueña del pagaré.
empresaActualIdentificacion	String	Body	Identificación de la empresa actual, que es dueña del pagaré.
ultimoEndosoFecha	String	Body	Fecha y hora, del último endoso del pagaré.
ultimoEndosoEstado	String	Body	El estado del último endoso.
ultimoEndosoEmpresaDestinoId	String	Body	Id de la última empresa, a la cual le endosaron el pagaré.
ultimoEndosoEmpresaDestinoIdentificacion	String	Body	Identificación de la última empresa, a la cual le endosaron el pagaré.
ultimoEndosoEmpresaDestinoNombre	String	Body	Nombre de la última empresa. a la cual le endosaron el pagaré.

3.3.3. Información

Con este servicio, puedes fácilmente revisar el estado de un proceso que te interese, obteniendo detalles sobre sus transacciones, documentos y firmantes. Solo necesitas ingresar el idProcesoClienteExterno del proceso para consultar el estado.

3.3.3.1. Operación

Método HTTP	Nombre operación	Descripción
GET	/informacion	Muestra el estado del proceso consultado.

3.3.3.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
IdProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	Si

Consulta:

3.3.3.3. Respuesta

Los siguientes son ejemplos de sus posibles respuestas:

Exitosa:
No exitosa
No se encuentra la información enviada:

3.3.3.4. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
IdProcesoClienteExterno	String	Body	Código de proceso único generado para el proceso.
FechaCreacion	Date	Body	Fecha y hora de creación del proceso.
nombre	String	Body	Nombre del solicitante del crédito.
apellido	String	Body	Apellido del solicitante del crédito.
identificacionCliente	String	Body	Identificación del cliente.
identificacionComercio	String	Body	Identificación del comercio
transacciones
IdTransaccion	String	Body	Código de proceso único generado para la transacción.
fechaTransaccion	String	Body	Fecha y hora de transacción del proceso.
Estado	String	Body	Estado en el que se encuentra el proceso.
tipo	String	Body	Tipo de consulta realizada.
documentos
tipoDocumento	String	Body	Descripción del tipo de documento.
serial	String	Body	Serial del documento.
estadoMiFirma	String	Body	Estado en el que se encuentra el documento en Mi Firma.
firmantes	String	Body
nombre	String	Body	Nombre del firmante
correo	String	Body	Correo electrónico del firmante.
celular	String	Body	Celular del firmante.
estado	String	Body	Estado de la firma.
detalle	String	Body	Detalles de la consulta.

3.3.4 Estado

Con este servicio, puedes fácilmente revisar el estado del proceso que te interesa. Solo necesitas ingresar el idProcesoClienteExterno del proceso:

3.3.4.1. Operación

Método HTTP	Nombre Operación	Descripción
GET	/ consultarEstado	Muestra el estado del proceso consultado.

3.3.4.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
IdProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	Si

Consulta:

3.3.4.3. Respuesta:

Los siguientes son ejemplos de sus posibles respuestas:

Exitosa:
No Exitosa:
No se encuentra la información enviada:

3.3.4.4. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
IdProcesoClienteExterno	String	Body	Código de proceso único generado para el proceso.
FechaCreacion	Date	Body	Fecha y hora de creación del proceso.
transacciones
IdTransaccion	integer	Body	Código de proceso único generado para la transacción.
fechaTransaccion	String	Body	Fecha y hora de transacción del proceso.
Estado	String	Body	Estado en el que se encuentra el proceso.
tipo	String	Body	Tipo de transacción realizada.

3.3.5 Documento /Estado

Con este servicio, puedes verificar cómo van las firmas de tus documentos. Tienes dos opciones para hacerlo: usando el número de serie del documento (serialDocumento) o el número de la transacción (idTransacción).

3.3.5.1. Operación

Método HTTP	Nombre Operación	Descripción
GET	/documento/estado	Muestra el estado de las firmas del documento.

3.3.5.2. Estructura modelo consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
serialDocumento	String	Parameters	Código de proceso único para cada solicitud realizada al servicio.	Si
idTransaccion	String	Parameters	Muestra el Id de la transacción.	Si

Consulta:

3.3.5.3. Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
No exitosa:

3.3.5.4. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
estadoDocumento	String	Body	Consulta el estado del documento.
documentoFirmantesEstados	String	Body	Muestra el estado de los documentos firmados.
email	String	Body	Muestra el email al que fue enviado el estado del documento consultado.
estado	String	Body	Muestra el estado actual del documento; ATDP= 1 Pagaré= 2 Anexo= 3
Tipo	String	Body	Muestra el tipo de transacción realizada; Desconocido= 0 Ani= 1 Emision_Sencilla= 2 Enviar= 3 Factura= 4 Cedula= 5 Voucher= 6 Iniciar= 7 ATDP= 8 Emision_Multiple= 9 Base64= 10 Emision_Base_64= 11

3.4 Proceso

3.4.1 Consulta ANI

Con este servicio, puedes consultar fácilmente el documento de identidad en el servicio ANI y emitir documentos a través de este proceso.

3.4.1.1 Operación

Método HTTP	Nombre Operación	Descripción
POST	proceso/consulta ANI	Emite un documento para ser firmado por el solicitante y codeudor del crédito.

3.4.1.2 Estructura modelo consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
IdentificacionComercio	String	Body	Número asignado a cada comercio.	SI
Documento	String	Body	Número de documento propio del cliente.	SI
TipoDocumento	integer	Body	Código del tipo de identificación. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	SI

3.4.1.3 Petición

{
"IdProcesoClienteExterno": "",
"IdentificacionComercio":null,
"Documento": "",
"TipoDocumento": 0
}

3.4.1.4. Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
No Exitosa:
Fallida por flujo:

3.4.1.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.
doumento	String	Body	Número de documento del cliente.
fechaConsulta	Date	Body	Fecha y hora de la consulta.
estado	String	Body	Estado de la consulta.
fechaDefuncion	String	Body	Fecha de la consulta.
fechaExpedicion	String	Body	Fecha de expedición de la consulta.
departamentoExpedicion	String	Body	Departamento de expedición de la consulta.
municipioExpedición	String	Body	Municipio de expedición de la consulta.
lugarExpedicion	String	Body	Lugar de expedición de la consulta.
primerNombre	String	Body	Primer nombre de la persona consultante.
segundoNombre	String	Body	Segundo nombre de la persona consultante.
primerApellido	String	Body	Primer apellido de la persona consultante.
segundoApellido	String	Body	Segundo apellido de la persona consultante.

3.4.2 Anexo

Con este servicio, puedes guardar fácilmente los documentos de tipo cédula y facturación para añadirlos a la información del solicitante del crédito y sus codeudores, según sea necesario.

3.4.2.1. Operación

Método HTTP	Nombre Operación	Descripción
POST	/anexo	Almacenan los documentos de tipo cedula y facturación.

3.4.2.2. Estructura modelo consulta

Nombre	Ubicación	Descripción	Requerido
idProcesoClienteExterno	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
tipoContenido	Body	Se indica el formato del archivo PNG, PDF, JPG.	SI
tipo	Body	Se debe indicar si el documento a generar “cedula” o “factura”.	SI
nombre	Body	Nombre del documento generar	SI
base64	Body	En este espacio se debe pegar el archivo codificado en base 64.	SI

Nota: Para el adjunto del documento en base64, asegúrate de que no supere los 10 MB.

3.4.2.3. Petición

{
"idProcesoClienteExterno": " 001",
"tipoContenido":"png",
"tipo":"cedula",
"nombre":"cedulaprueba",
"base64":""
}

3.4.2.4. Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir.

Exitosa:
No exitosa:

3.4.2.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
serialDcto	String	Body	Código de proceso único generado para el proceso.

3.4.3. Emitir documento

Con este servicio, puedes generar los documentos (pagaré, ATDP, etc.) para que luego sean firmados por el solicitante del crédito y sus codeudores, según sea necesario.

3.4.3.1 Operación

Método HTTP	Nombre Operación	Descripción
POST	/ emitirDocumento	Emite los documentos para ser firmados por el solicitante y codeudor del crédito.

3.4.3.2 Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
identificacionComercio	int	Body	Identificación del comercio.	SI
requiereATDP	Boolean	Body	Indica si se requiere ATDP previo.	SI
IdTipoDocumento	String	Body	Código asociado al Tipo de documento; ATDP = 1, Pagare = 2, Anexo = 3, Factura = 4, Cedula = 5, Voucher = 6, Otro = 7.	SI
serialPlantilla	String	Body	Número único de plantilla.	SI
Anotaciones	String	Body	Son el conjunto de información que va a llevar la plantilla, caída de datos.	SI
Firmantes	String	Body	Es el conjunto de información de los firmantes que va a llevar el documento.	SI
Nombre	String	Body	Nombre del firmante.	SI
Apellido	String	Body	Apellido del firmante.	SI
Identificacion	String	Body	# de Identificación del firmante.	SI
TipoIdentificacion	int	Body	Código del tipo de identificación. Información suministrada al cliente. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	SI
Correo	String	Body	Correo del firmante.	SI
Celular	String	Body	Celular del firmante.	SI

3.4.3.3 Petición

 {
    "idTipoDocumento": "2",
    "requiereATDP": "false",
    "idProcesoClienteExterno": "DEV110402",
    "identificacionComercio": "900032774",
    "serialPlantilla": "90533",
    "anotaciones": [
        "UNO",
        "DOS",
        "TRES",
        "CUATRO"
    ],
    "firmantes": [
        {
            "nombre": "nombre firmante",
            "apellido": "apellido firmante",
            "identificacion": "identificación firmante",
            "tipoIdentificacion": "104",
            "correo": "firmante2@yopmail.com",
            "celular": "numero celular firmante"
        },
        {
            "nombre": " nombre firmante",
            "apellido": "apellido firmante",
            "identificacion": "identificación firmante",
            "tipoIdentificacion": "104",
            "correo": "firmante3@yopmail.com",
            "celular": "numero celular firmante"
        }
    ]
}

3.4.3.4 Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir.

Exitosa:
Fallida por datos:
Fallida por flujo:

3.4.3.5 Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
transaccionId	String	Body	Numero asignado a cada transacción realizada.
Mensaje	String	Body	Mensaje de respuesta de la transacción.

3.4.4. Emitir múltiples documentos

Con este servicio, puedes generar varios documentos de una sola vez (como pagarés y otros documentos adicionales) para que luego sean firmados por el solicitante del crédito y sus codeudores, según sea necesario.

3.4.4.1 Operación

Método HTTP	Nombre Operación	Descripción
POST	proceso/emitirMultipleDocumento	Emite varios documentos para ser firmados por el solicitante y codeudor del crédito.

3.4.4.2 Estructura modelo consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
Firmantes	String	Body	Es el conjunto de información de los firmantes que va a llevar el documento.	SI
nombre	String	Body	Nombre del firmante.	SI
apellido	String	Body	Apellido del firmante.	SI
identificacion	String	Body	# de Identificación del firmante.	SI
tipoIdentificacion	int	Body	Código del tipo de identificación. Información suministrada al cliente. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	SI
correo	String	Body	Correo del firmante.	SI
celular	String	Body	Celular del firmante.	SI
documentos	String	Body	Es el conjunto de información de los documentos que va a llevar el documento.	SI
IdTipoDocumento	int	Body	Código asociado al Tipo de documento; ATDP = 1, Pagare = 2, Anexo = 3, Factura = 4, Cedula = 5, Voucher = 6, Otro = 7.	SI
SerialPlantilla	String	Body		SI
Anotaciones	String	Body	Son el conjunto de información que va a llevar la plantilla, caída de datos.	SI
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
identificacionComercio	String	Body	Número asignado a cada comercio.	SI
requiereATDP	Boolean	Body	Indica si se requiere ATDP previo.	SI

3.4.4.3 Petición

{
"documentos": [
   {
       "idTipoDocumento": 0,
       "serialPlantilla": "string",
       "anotaciones": [
           "anotacion"
       ]
     },
     {
       "idTipoDocumento": 0,
       "serialPlantilla": "string",
       "anotaciones": [
           "anotacion"
       ]
     },
     {
       "idTipoDocumento": 0,
       "serialPlantilla": "string",
       "anotaciones": [
           "anotacion"
       ]
     }
],
"firmantes": [
     {
         "nombre": "string",
         "apellido": "string",
         "identificacion": "string",
         "tipoIdentificacion": "104",
         "correo": "string",
         "celular": "string"
     }
   ],
"idProcesoClienteExterno": "string",
"identificacionComercio": "string",
"requiereATDP": false,
"tipoEndoso": 0
}

3.4.4.4 Respuesta

Aquí te compartimos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
No Exitosa:
Fallida por flujo:

3.4.4.5 Estructura modelo de Respuesta

Nombre	Tipo	Ubicación	Descripción
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.
idtransaccion	String	Body	Código único de transacción del documento.
tipoTransaccion	String	Body	Código para identificar el tipo de endoso. Se puede usar el valor por defecto 0; o los siguientes códigos: 1: En propiedad con Responsabilidad 2: En propiedad sin Responsabilidad 3: En Garantía 4: En Procuración
estadoTransaccion	String	Body	Estado en el que se encuentra la transacción.
fechaGeneracion	Date	Body	Fecha en que fue generado el documento.
documentos	String	Body	Serie de documentos enlistados.
serialDto	String	Body	Numero único perteneciente a cada documento.
tipoDto	String	Body	El tipo de documento.
estadoDto	String	Body	Estado en el que se encuentra cada documento.

3.4.5. Emitir Base64

Con este servicio, puedes generar documentos en formato Base64 (como pagarés, ATDP, etc.) para que luego sean firmados por el solicitante del crédito y sus codeudores, según sea necesario.

3.4.5.1 Operación

Método HTTP	Nombre Operación	Descripción
POST	/ emitirBase64	Emite los documentos desde formato base64 para ser firmados por el solicitante y codeudor del crédito.

3.4.5.2 Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
tipoServicio	String	Body	Número del tipo de servicio O = Emisión por proceso desde MiFirma 1 = Emisión por proceso Embebido	Si
IdTipoDocumento	String	Body	Código asociado al Tipo de documento; Pagare = 2	SI
base64	String	Body	Texto de la plantilla en formato base64 con campos ya configurados.	Si
Firmantes	String	Body	Es el conjunto de información de los firmantes que va a llevar el documento.	SI
nombre	String	Body	Nombre del firmante.	SI
apellido	String	Body	Apellido del firmante.	SI
Identificacion	String	Body	# de Identificación del firmante.	SI
tipoIdentificacion	int	Body	Código del tipo de identificación. Información suministrada al cliente. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	SI
correo	String	Body	Correo del firmante.	SI
celular	String	Body	Celular del firmante.	SI
posicionX	int	Body	Coordenadas en el eje X para la ubicación de la firma.	(Solo para Proceso de MiFirma)
posicionY	int	Body	Coordenadas en el eje Y para la ubicación de la firma.	(Solo para Proceso de MiFirma)
anchoFirma	int	Body	Dimensiones del campo de firma en anchura.	(Solo para Proceso de MiFirma)
altoFirma	int	Body	Dimensiones del campo de firma en altura.	(Solo para Proceso de MiFirma)
paginaFirma	int	Body	Número de la página en el documento donde se va a ubicar el campo de firma. NOTA: El número de la primera página inicia en cero. Ejemplo: Página 1 = 0 Página 2 = 1	(Solo para Proceso de MiFirma)
campoFirma	String	Body	Campo de firma para el proceso Embebido	(Solo para embebido)
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
identificacionComercio	int	Body	Identificación del comercio.	SI
requiereATDP	Boolean	Body	Indica si se requiere ATDP previo.	SI

Recuerda: El documento en formato base64 debe incluir un campo de firma, y ese es el que se especifica en la solicitud para colocar la firma electrónica "CampoFirma".

3.4.5.3 Petición

"tipoServicio": 0,
"idTipoDocumento": 0,
"base64": "string",
"firmantes": [
   {
     "nombre": "string",
     "apellido": "string",
     "identificacion": "string",
     "tipoIdentificacion": 0,
     "correo": "string",
     "celular": "string",
     "posicionX": 0,
     "posicionY": 0,
     "width": 0,
     "height": 0,
     "paginaFirma": 0
     "campoFirma": "string"
   }
],
"idProcesoClienteExterno": "string",
"identificacionComercio": "string",
"requiereATDP": true
}

NOTA: No Eliminar ninguno de los campos, así no se utilice o no sean necesarios en la petición que se emita.

3.4.5.4 Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir.

Exitosa:
Fallida por datos:
Fallida por flujo:

3.4.5.5 Estructura modelo de respuesta Mi Firma:

Nombre	Tipo	Ubicación	Descripción
idProcesoClienteExterno	Int	Body	Código de proceso único para cada solicitud realizada al servicio.
idTransaccion	String	Body	Número asignado a cada transacción realizada.
tipoTransaccion	String	Body	El tipo de transacción realizada.
estadoTransaccion	String	Body	Muestra el estado de la transacción.
fechaGeneracion	Date	Body	Fecha y hora en la que se generó el documento.
documentos	String	Body	Muestra la información de los distintos documentos.
serialDto	String	Body	Número de serial del documento.
tipoDto	String	Body	Muestra el tipo de documento. Anexos (ATDP, Pagaré, Voucher)
estadoDto	String	Body	Estado general del documento.
listUrls	String	Body	Listado de correos y URL´s de firma del documento.
email	String	Body	Correo al cual se generó la solicitud de firma.
url	String	Body	Enlace de firma de documento.

3.4.5.6 Estructura modelo de respuesta embebido

Nombre	Tipo	Ubicación	Descripción
idTransaccion	String	Body	Número asignado a cada transacción realizada.
Mensaje	String	Body	Mensaje si el proceso de emisión

3.5 Proceso embebido

3.5.1 Plantillas - Cargar una plantilla

Por medio de este servicio se pueden cargar plantillas al sistema para el proceso embebido.

3.5.1.1. Operación

Método HTTP	Nombre Operación	Descripción
POST	/plantillas	Permite subir plantillas al sistema para proceso embebido.

3.5.1.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
base64	String	Body	Código en formato base64 de la plantilla.	SI
nombrePlantilla	String	Body	Nombre que se le asignará a la plantilla.	SI
IdTipoDocumento	String	Body	Código asociado al Tipo de documento; ATDP = 1, Pagare = 2, Anexo = 3, Factura = 4, Cedula = 5, Voucher = 6, Otro = 7.	SI

3.5.1.3. Petición

{
"base64": "string",
"nombrePlantilla": "string",
"idTipoDocumento": 0
}

3.5.1.4. Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.1.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
serialPlantilla	String	Body	Código serial de la plantilla.

3.5.2 Plantillas - Obtener campos de una plantilla

Con este servicio, puedes fácilmente obtener los campos de una plantilla:

3.5.2.1. Operación

Método HTTP	Nombre Operación	Descripción
GET	/plantillas	Permite obtener los campos de una plantilla.

3.5.2.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
plantillas				Si
serialPlantilla	String	Body	Identificador único de la plantilla.	Si

3.5.2.3. Petición

{
"plantillas": [
   {
     "serialPlantilla": "string"
   }
]
}

3.5.2.4. Respuesta

Aquí te mostramos algunos ejemplos de las respuestas que podrías recibir.

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.2.5 Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
nombre	String	Body	Nombre de la plantilla
serial	String	Body	Código serial de la plantilla.
activa	Boolean	Body	Estado de la plantilla.
fechaActualizacion	Date	Body	Fecha de actualización de la plantilla.
tipoDocumento	String	Body	El tipo de documento que tiene la plantilla.
campos	String	Body	Campos que tiene la plantilla.

3.5.3 Plantillas - Actualizar una plantilla

Con este servicio, puedes fácilmente actualizar una plantilla que ya tengas:

3.5.3.1. Operación

Método HTTP	Nombre Operación	Descripción
PUT	/plantillas/{serialPlantilla}	Permite obtener los campos de una plantilla.

3.5.3.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
serialPlantilla	String	Body	Identificador único de la plantilla.	Si
Base64	String	Body	Código en formato base64 de la plantilla.	Si

3.5.3.3. Petición

{
"base64": "string"
}

3.5.3.4. Respuesta

Aquí te mostramos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.3.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
Respuesta	Boolean	Body	Estado de la actualización. Verdadero o falso.

3.5.4. Descarga pagare

Con este servicio, puedes conseguir un pagaré ya firmado en formato base64 o a través de un enlace URL.

3.5.4.1. Operación

Método HTTP	Nombre Operación	Descripción
GET	/pagares/descarga	Permite obtener un pagaré firmado.

3.5.4.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
serialDocumento	String	Parameters	Identificador único del documento.	SI
tipoDocumento	String	Lista Desplegable	Tipo de documento, del cual deseas obtener la descarga	SI
tipoFormato	String	Lista Desplegable	Formato con el cual se desea obtener el archivo	SI

3.5.4.3. Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir:

Exitosa - URL:
Exitosa - Base64:
Fallida por datos:
Fallida por flujo:

3.5.4.4. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
Respuesta 1	String	Body	Texto en formato base64.
Respuesta 2	String	Body	URL del pagaré.

3.5.5. Previsualizar plantilla

Con este servicio, puedes darle un vistazo a cómo luce un pagaré completado a partir de una plantilla. ¡Y lo mejor de todo es que lo obtienes en formato base64!

3.5.5.1. Operación

Método HTTP	Nombre Operación	Descripción
GET	/pagares/previsualizar	Permite previsualizar como se ve un pagaré diligenciado desde una plantilla en formato base64.

3.5.5.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
idProcesoClienteExterno	String	Body	Identificador único del documento.	SI
plantillas
serialPlantilla	String	Body	Identificador único de la plantilla.
anotaciones	String	Body	Anotaciones que lleva la plantilla a diligenciar.	SI

3.5.5.3. Petición

{
"idProcesoClienteExterno": "string",
"plantillas": [
   {
     "serialPlantilla": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "anotaciones": [
       {
         "nombre": "string",
         "valor": "string"
       }
     ]
   }
]
}

3.5.5.4. Respuesta

Los siguientes son ejemplos de sus posibles respuestas.

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.5.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
transaccionRegistrada	Boolean	Body	Confirmación del registro de la transacción de forma afirmativa o negativa.
archivos
Base64	String	Body	Texto en formato bas64 con la plantilla diligenciada.

3.5.6. Emitir múltiples documentos

Con este servicio, puedes generar los documentos (como pagarés, ATDP, etc.) a través del proceso embebido para que luego sean firmados por el solicitante del crédito y sus codeudores, según sea necesario.

3.5.6.1. Operación

Método HTTP	Nombre operación	Descripción
POST	/proceso-embebido/pagares/emitir	Emite los documentos para ser firmados por el solicitante del crédito.

3.5.6.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
identificacionComercio	int	Body	Identificación del comercio.	SI
requiereATDP	Boolean	Body	Indica si se requiere ATDP previo.	SI
Firmantes	String	Body	Es el conjunto de información de los firmantes que va a llevar el documento.	SI
Nombre	String	Body	Nombre del firmante.	SI
Apellido	String	Body	Apellido del firmante.	SI
Identificacion	String	Body	# de Identificación del firmante.	SI
TipoIdentificacion	int	Body	Código del tipo de identificación. Información suministrada al cliente. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	SI
Correo	String	Body	Correo del firmante.	SI
Celular	String	Body	Celular del firmante.	SI
campoFirma	String	Body	Campo en el cual se registrará la firma del documento.
documentos	String	Body	Conjunto de información donde se indican las plantillas y las anotaciones que llevaran.
IdTipoDocumento	String	Body	Código asociado al Tipo de documento; ATDP = 1, Pagare = 2, Anexo = 3, Factura = 4, Cedula = 5, Voucher = 6, Otro = 7.	SI
serialPlantilla	String	Body	Número único de plantilla.	SI
camposPlantilla	String	Body	Son los campos que se diligenciaran en la plantilla.	SI

3.5.6.3. Petición

{
    "idProcesoClienteExterno": "string",
    "identificacionComercio": "string",
    "requiereATDP": true,
    "firmantes": [
      {
        "nombre": "string",
        "apellido": "string",
        "identificacion": "string",
        "tipoIdentificacion": 0,
        "correo": "string",
        "celular": "string",
        "campoFirma": "string"
      }
    ],
    "documentos": [
      {
        "idTipoDocumento": 0,
        "serialPlantilla": "string",
        "camposPlantilla": [
          null
        ]
      }
    ]
}

3.5.6.4. Respuesta

Aquí te dejamos algunos ejemplos de las respuestas que podrías recibir:

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.6.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
transaccionId	String	Body	Numero asignado a cada transacción realizada.
mensaje	String	Body	Mensaje de respuesta de la transacción.

3.5.7. Generar pagaré con código NUIP

Con este servicio, puedes crear un pagaré con un código NUIP.

3.5.7.1. Operación

Método HTTP	Nombre Operación	Descripción
POST	/proceso-embebido/pagares/generar	Genera un pagaré con código NUIP.

3.5.7.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
codigoNUIP	String	Body	Se debe ingresar el código NUIP.	SI
idProcesoClienteExterno	String	Body	Código de proceso único para cada solicitud realizada al servicio.	SI
identificacionComercio	int	Body	Identificación del comercio.	SI
requiereATDP	Boolean	Body	Indica si se requiere ATDP previo.	SI
Firmantes	String	Body	Es el conjunto de información de los firmantes que va a llevar el documento.	SI
Nombre	String	Body	Nombre del firmante.	SI
Apellido	String	Body	Apellido del firmante.	SI
Identificacion	String	Body	Número de Identificación del firmante.	SI
TipoIdentificacion	int	Body	Código del tipo de identificación. Información suministrada al cliente. 104: Cedula de Ciudadanía 106: NIT 107: Cedula de Extranjería 108: Tarjeta de Identidad 109: Permiso Especial Permanecía 110: Pasaporte	SI
Correo	String	Body	Correo electrónico del firmante.	SI
Celular	String	Body	Número celular del firmante.	SI
campoFirma	String	Body	Campo en el cual se registrará la firma del documento.	SI
documentos	String	Body	Conjunto de información donde se indican las plantillas y las anotaciones que llevaran.	SI
IdTipoDocumento	String	Body	Código asociado al Tipo de documento; Pagare = 2,	SI
serialPlantilla	String	Body	Código único de plantilla.	SI
camposPlantilla	String	Body	Son los campos que se diligenciaran en la plantilla.	SI

3.5.7.3. Petición

{
"codigoNUIP": "string",
"idProcesoClienteExterno": "string",
"identificacionComercio": "string",
"requiereATDP": false,
"firmantes": [
   {
     "nombre": "string",
     "apellido": "string",
     "identificacion": "string",
     "tipoIdentificacion": 0,
     "correo": "string",
     "celular": "string",
     "campoFirma": "string"
   }
],
"documentos": [
   {
     "idTipoDocumento": 0,
     "serialPlantilla": "string",
     "camposPlantilla": [
       null
     ]
   }
]
}

3.5.7.4. Respuesta

Los siguientes son ejemplos de sus posibles respuestas:

Exitosa:
Fallida por datos:
Falta de datos:

3.5.7.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
Serial	String	Body	Número serial asignado al generar exitosamente un pagaré con código NUIP
mensaje	String	Body	Mensaje de respuesta de la transacción.

3.5.8. Validar OTP

Con este servicio, puedes verificar fácilmente los códigos OTP que se envían al firmante.

3.5.8.1. Operación

Método HTTP	Nombre Operación	Descripción
POST	/proceso-embebido/pagares/validarOTP	Valida los códigos OTP enviados al firmante.

3.5.8.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
transaccionId	String	Body	Número asignado a cada transacción realizada.	SI
numeroCelular	String	Body	Celular del firmante.	SI
otpNumero	String	Body	Código enviado al firmante para completar el proceso de firma.	SI

3.5.8.3. Petición

{
"idTransaccion": 0,
"numeroCelular": "string",
"otpNumero": "string"
}

3.5.8.4. Respuesta

Los siguientes son ejemplos de sus posibles respuestas:

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.8.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
response	String	Body	Respuesta de la transacción.

3.5.9. Renviar OTP

Con este servicio, puedes reenviar fácilmente los códigos OTP al firmante.

3.5.9.1. Operación

Método HTTP	Nombre Operación	Descripción
POST	/proceso-embebido/pagares/reenvioOTP	Generar reenvíos de códigos OTP´s al firmante.

3.5.9.2. Estructura modelo de consulta

Nombre	Tipo	Ubicación	Descripción	Requerido
transaccionId	String	Body	Número asignado a cada transacción realizada.	SI
numeroCelular	String	Body	Celular del firmante.	SI

3.5.9.3. Petición

{
"idTransaccion": 0,
"numeroCelular": "string",
}

3.5.9.4. Respuesta

Los siguientes son ejemplos de sus posibles respuestas.

Exitosa:
Fallida por datos:
Fallida por flujo:

3.5.9.5. Estructura modelo de respuesta

Nombre	Tipo	Ubicación	Descripción
response	String	Body	Respuesta de la transacción.

4. REQUISITOS DEL SISTEMA

SERVIDOR

Como el sistema no maneja grandes volúmenes de información, es perfectamente factible que el Application Server y el Database Server compartan el mismo servidor. A continuación, te mostramos los detalles de cada uno de estos servidores.

COMPONENTE DE HARDWARE	MÍNIMO	RECOMENDADO
Memoria RAM	2 GB	4.8 GB o superior
Procesadores	2 de 3Ghz	8 de 3Ghz o superior
Disco Duro	2 particiones de 80 GB	2 particiones de 120 GB o superior
Red	1 tarjeta de Red estándar	1 tarjeta de Red Fibra Óptica

EQUIPO DE CLIENTE

Para que puedas disfrutar de la aplicación, asegúrate de que los PC’s de los usuarios cuenten con las siguientes características:

COMPONENTE DE HARDWARE	MÍNIMO	RECOMENDADO
Memoria RAM	512 MB	1 GB
Procesadores	1 de 1.7 GHz	2 de 2.4 GHz
Espacio necesario en Disco	150 MB	-

5. CONTROL DE CAMBIOS

VERSIÓN	FECHA	DESCRIPCIÓN
1	2021-11-09	Creación del documento.
2	2022-02-25	Ajuste de imágenes.
3	2022-03-11	Ingreso de nuevos módulos.
4	2022-06-01	Ajuste de redacción e imágenes.
5	2022-12-05	Actualización nuevos procesos.
6	2023-14-04	Actualización de documento.
7	2023-08-02	Reenviar OTP.
8	2023-08-03	Corrección de la URL del API de Mis Pagares en el numeral 3.1.
9	2023-08-09	Se actualiza método de emisión base64. Numeral 3.4.4.
10	2023-10-04	Actualización emisión base64 para embebido e Identificación para los documentos.
11	2023-10-23	Actualización método Descarga Pagare.
12	2024-09-03	Actualización formato de los anexos y consulta de ANI.

6. PROPIEDAD DE OLIMPIA

El presente documento es de carácter confidencial y está protegido por las normas de derechos de autor, cualquier reproducción, distribución o modificación total o parcial a usuarios no autorizados o cualquier uso indebido de la información confidencial será considerado un delito conforme a lo establecido por el Código Penal y Leyes vigentes del estado Colombiano.

Documento de Olimpia - Uso PÚBLICO