🔵 Crear de paquete de firma

POST /document/save

Este servicio permite generar paquete de documentos a partir de una plantilla de Auco o de un archivo PDF. Al terminar el proceso, obtendras cada documento con su propio certificado de firma.

info

Antes de integrar este endopint puede necesitar ver cómo definir posiciones de firma y configuraciones de validación de identidad.

Pasos para crear un paquete de documento a través de una plantilla automatizada:

Consultar plantillas o documentos personalizados disponibles: Debe iniciar consultando los recursos disponibles (plantillas propias o de Auco) para identificar el documento base que desea utilizar.
Obtener el identificador (_id) del documento base: Una vez identificada la plantilla o documento deseado, obtenga su _id para poder continuar con el proceso.
Consultar variables requeridas del documento seleccionado: Utilice el servicio correspondiente para recuperar la lista de variables que necesita completar. Este paso es esencial para construir correctamente la solicitud de creación del documento.
Construir y enviar el request de creación: Con la información de las variables, puede armar el cuerpo de la solicitud (POST) para generar el documento.

info

Si desea hacerlo por medio de PDF, no es necesario enviar el archivo en la petición inicial. Al final, se le retornará una URL firmada por cada documento del paquete

A continuación se describen los parámetros necesarios para este servicio, junto con ejemplos y posibles respuestas del sistema.

Autenticación

Incluye tu llave privada en el encabezado Authorization.

Authorization: prk_xxx...

Parámetros de creación

Nombre	Tipo	Requerido	Descripción
`email`	String	Requerido	Correo electrónico del creador del proceso.
`document`	String	Condicional	ID del documento personalizado o la plantilla Auco Sólo si se desea realizar por medio de plantilla.
`name`	String	Requerido	Nombre del proceso del documento a firmar, solo si el proceso de adjuntos incluye firma de documento.
`message`	String	Requerido	Mensaje que llegará en el cuerpo del correo notificando a los firmantes u aprobadores del documento.
`subject`	String	Requerido	Asunto con el que será enviado el correo de notificación a los firmantes u aprobadores.
`folder`	String	Condicional	Si desea guardar este proceso en una carpeta específica, en este parámetro debe igresar el path de dicha carpeta, tenga en cuenta que la carpeta debe existir y pertenecer al creador del proceso.
`remember`	Number	Condicional	Parámetro que habilita recordatorios automáticos con el lapso de tiempo (horas) entre cada notificación. Debe ser múltiplo de 3
`expiredDate`	Date	Opcional	Fecha de expiración del documento. Esta debe ser mayor a 3 días de la fecha de creación del proceso y se envia en formato Date JSON.
`camera`	Boolean	Opcional	Este parámetro indica si es obligatoria la validación con foto, por defecto va en `false`.
`otpCode`	Boolean	Opcional	Este parámetro indica si es obligatorio la validación por código OTP, por defecto va en `false`.
`options`	Object	Opcional	En este parámetro se indican las especificaciones de la validación de identidad. Ver más
`notification`	Boolean	Opcional	Este parámetro define si se va a anotificar a los participante una vez creado el proceso, por defecto es `true`
`data`	Array	Condicional	En este parámetro se envían todos los datos que necestia la plantilla para generar el documento. Sólo si se desea realizar por medio de plantilla.
`data[x].key`	String	Requerido	Nombre del parámetro registrado en la plantilla.
`data[x].value`	String	Requerido	Valor asignado al parámtro.
`documents` *	Array	Requerido	En este cambo se envía una lista de tipo objeto que contiene cada documento.
`documents[0].name`	Array	Opcional	Este parámetro es una lista de objetos que define los participantes que no hacen parte del proceso de firma, pero que se desea que puedan observar cada fase del proceso de firma.
`documents[0].readers`	Array	Opcional	Este parámetro es una lista de objetos que define los participantes que no hacen parte del proceso de firma, pero que se desea que puedan observar cada fase del proceso de firma.
`documents[0].readers[x].name`	String	Requerido	nombre del lector.
`document[0].readers[x].email`	String	Requerido	correo del lector.
`documents[0].document.signProfile`	Array	Requerido	Este campo es una lista de objetos, donde se encuentra la información de cada firmante o aprobador para su notificación y firma.
`documents[0].signProfile[x].name`	String	Requerido	nombre del firmante.
`documents[0].signProfile[x].email`	String	Requerido	correo del firmante.
`documents[0].signProfile[x].phone`	String	Requerido	número de teléfono del firmante.
`documents[0].signProfile[x].role`	String	Condicional	Este parámetro define el role del participante, puede ser `'APPROVER'` o `'SIGNER'`.
`documents[0].signProfile[x].order`	String	Condicional	Este parámetro define el orden en que se realizará el proceso de notificación para firma o aprobación.
`documents[0].signProfile[x].position`	Array	Condicional	En este parámetro se envían las posiciones de firma de este firmante en cada página. Las posiciones de firma pueden estar previamente cargadas en plantillas, obtenga mas informacion en .
`documents[0].signProfile[x].type`	Array	Condicional	Nombre con el que se identifica el tipo de firmante en caso de estar pre guardadas en una plantilla, por ejemplo: `'codeudor'`.
`documents[0].signProfile[x].label`	Boolean	Condicional	Parámetro que indica si se realizará el posicionamiento de firmas por medio de labels en el pdf.
`documents[0].signProfile[x].options`	Object	Opcional	Permite definir validaciones personalizadas para un firmante específico. Si se desea aplicar validaciones de forma individual por firmante, Ver más.
`documents[0].signProfile[x].camera`	Boolean	Opcional	Si se desea tener validaciones individuales por firmante y se requiere validación con foto o video, se debe enviar este parametro en `true` por defecto es `false`.
`documents[0].signProfile[x].otpCode`	Boolean	Opcional	Si se desea tener validaciones individuales por firmante y se requiere validación con otp, se debe enviar este parametro en `true` por defecto es `false`.
`documents[0].signProfile[x].both`	Boolean	Opcional	Si se desea tener validaciones individuales por firmante y se requiere que el proceso de firma se pueda hacer por medio de WhatsApp y/o correo electrónico, se debe enviar este parámetro en `true`, por defecto es `false`.

🧪 Ejemplos de uso

tip

Puedes copiar cualquiera de los ejemplos según el lenguaje de tu preferencia.

Recuerda que los correos electrónticos y números de teléfonos entre firmantes no se deben repetir.
Los lectores van a recibir notificaciones por cada actualización en el proceso de firma.
Formato de fecha: 'DD/MM/AAAA'
Los números de teléfono deben tener el indicativo del país, por ejemplo: +57, +1, +52...

Paquete de documentos por medio de PDF

curl
Python
Node.js

curl --location 'https://dev.auco.ai/v1/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba paquete 2 documentos",
    "email": "example@auco.ai",
    "message": "Hola a todos, les comparto el paquete de documentos para la firma",
    "options": {
        "camera": "identification",
        "whatsapp": true
    },
    "camera": true,
    "otpCode": false,
    "documents": [
        {
            "name": "Documento 1",
            "signProfile": [
                {
                    "type": "solicitante",
                    "name": "Firmante 1",
                    "phone": "+573000000000",
                    "email": "example1@auco.ai"
                }
            ]
        },
        {
            "name": "Documento 2",
            "signProfile": [
                {
                    "type": "solicitante",
                    "name": "Firmante 1",
                    "phone": "+573000000000",
                    "email": "example2@auco.ai"
                }
            ]
        }
    ]
}

import requests
import json

url = "https://dev.auco.ai/v1/ext/document/many"

payload = json.dumps({
  "name": "Prueba notification2",
  "email": "example@auco.ai",
  "message": "Hola a todos, les comparto el paquete de documentos para la firma",
  "options": {
    "camera": "identification",
    "whatsapp": True
  },
  "camera": True,
  "otpCode": False,
  "documents": [
    {
      "name": "Documento 1",
      "signProfile": [
        {
          "type": "solicitante",
          "name": "Firmante 1",
          "phone": "+573000000000",
          "email": "example1@auco.ai"
        }
      ]
    },
    {
      "name": "Documento 2",
      "signProfile": [
        {
          "type": "solicitante",
          "name": "Firmante 1",
          "phone": "+573000000000",
          "email": "example2@auco.ai"
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

const axios = require('axios');
let data = JSON.stringify({
  name: 'Prueba notification2',
  email: 'example@auco.ai',
  message: 'Hola a todos, les comparto el paquete de documentos para la firma',
  options: {
    camera: 'identification',
    whatsapp: true,
  },
  camera: true,
  otpCode: false,
  documents: [
    {
      name: 'Documento 1',
      signProfile: [
        {
          type: 'solicitante',
          name: 'Firmante 1',
          phone: '+573000000000',
          email: 'example1@auco.ai',
        },
      ],
    },
    {
      name: 'Documento 2',
      signProfile: [
        {
          type: 'solicitante',
          name: 'Firmante 1',
          phone: '+573000000000',
          email: 'example2@auco.ai',
        },
      ],
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://dev.auco.ai/v1/ext/document/many',
  headers: {
    Authorization: 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
    'Content-Type': 'application/json',
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Paquete de documentos por medio de plantillas personalizadas

curl
Python
Node.js

curl --location 'https://dev.auco.ai/v1/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba notification2",
    "email": "example@auco.ai",
    "message": "Hola a todos, les comparto el paquete de documentos para la firma",
    "options": {
        "camera": "identification",
        "whatsapp": true
    },
    "camera": true,
    "otpCode": false,
    "documents": [
        {
            "name": "Documento 1",
            "document": "documentId",
            "data": [
                {"key": "signer_nombre", "value":"firmante 1"},
                {"key": "signer_identification", "value":"cc"},
                {"key": "signer_phone", "value":"+573000000000"},
                {"key": "manager_name", "value":"manager 1"}
            ]
        },
        {
            "name": "Documento 2",
            "document": "documentId",
            "data": [
                {"key": "signer_nombre", "value":"firmante 1"},
                {"key": "signer_identification", "value":"cc"},
                {"key": "signer_phone", "value":"+573000000000"},
                {"key": "manager_name", "value":"manager 1"}
            ]
        }
    ]
}'

import requests
import json

url = "https://dev.auco.ai/v1/ext/document/many"

payload = json.dumps({
  "name": "Prueba notification2",
  "email": "example@auco.ai",
  "message": "Hola a todos, les comparto el paquete de documentos para la firma",
  "options": {
    "camera": "identification",
    "whatsapp": True
  },
  "camera": True,
  "otpCode": False,
  "documents": [
    {
      "name": "Documento 1",
      "document": "documentId",
      "data": [
        {
          "key": "signer_nombre",
          "value": "firmante 1"
        },
        {
          "key": "signer_identification",
          "value": "cc"
        },
        {
          "key": "signer_phone",
          "value": "+573000000000"
        },
        {
          "key": "manager_name",
          "value": "manager 1"
        }
      ]
    },
    {
      "name": "Documento 2",
      "document": "documentId",
      "data": [
        {
          "key": "signer_nombre",
          "value": "firmante 1"
        },
        {
          "key": "signer_identification",
          "value": "cc"
        },
        {
          "key": "signer_phone",
          "value": "+573000000000"
        },
        {
          "key": "manager_name",
          "value": "manager 1"
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

const axios = require('axios');
let data = JSON.stringify({
  name: 'Prueba notification2',
  email: 'example@auco.ai',
  message: 'Hola a todos, les comparto el paquete de documentos para la firma',
  options: {
    camera: 'identification',
    whatsapp: true,
  },
  camera: true,
  otpCode: false,
  documents: [
    {
      name: 'Documento 1',
      document: 'documentId',
      data: [
        {
          key: 'signer_nombre',
          value: 'firmante 1',
        },
        {
          key: 'signer_identification',
          value: 'cc',
        },
        {
          key: 'signer_phone',
          value: '+573000000000',
        },
        {
          key: 'manager_name',
          value: 'manager 1',
        },
      ],
    },
    {
      name: 'Documento 2',
      document: 'documentId',
      data: [
        {
          key: 'signer_nombre',
          value: 'firmante 1',
        },
        {
          key: 'signer_identification',
          value: 'cc',
        },
        {
          key: 'signer_phone',
          value: '+573000000000',
        },
        {
          key: 'manager_name',
          value: 'manager 1',
        },
      ],
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://dev.auco.ai/v1/ext/document/many',
  headers: {
    Authorization: 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
    'Content-Type': 'application/json',
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

📥 Ejemplos de respuesta

Paquede de documentos a través de PDF

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "GNAZED5HTR"
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "RC0OO75VL7"
    }
  ]
}

info

La URL firmada proporcionada en la respuesta es de un solo uso y estará disponible únicamente durante 5 segundos. Debe utilizarse para cargar el documento PDF en formato binario mediante una solicitud HTTP PUT.

A través de plantillas personalizadas

{
  "id": "packageId",
  "documents": [
    {
      "name": "Documento 1",
      "code": "GNAZED5HTR"
    },
    {
      "name": "Documento 2",
      "code": "RC0OO75VL7"
    }
  ]
}

⚠️ Respuestas de error

Código	Descripción
400	Faltan parámetros, o alguna de las validaciones no coinciden con las condiciones de aplicabilidad
401	Autenticación inválida o ausente

Pasos para crear un paquete de documento a través de una plantilla automatizada:​

Autenticación​

Parámetros de creación​

🧪 Ejemplos de uso​

Paquete de documentos por medio de PDF​

Paquete de documentos por medio de plantillas personalizadas​

📥 Ejemplos de respuesta​

Paquede de documentos a través de PDF​

A través de plantillas personalizadas​

⚠️ Respuestas de error​

Pasos para crear un paquete de documento a través de una plantilla automatizada:

Autenticación

Parámetros de creación

🧪 Ejemplos de uso

Paquete de documentos por medio de PDF

Paquete de documentos por medio de plantillas personalizadas

📥 Ejemplos de respuesta

Paquede de documentos a través de PDF

A través de plantillas personalizadas

⚠️ Respuestas de error