Criar processo de anexos

POST/package/uploadchave privadaprk_

Este serviço permite iniciar um processo para solicitar anexos para assinatura ou simplesmente anexos sem assinatura. Cada anexo pode ser configurado como obrigatório ou opcional.

info

Se você quiser incluir um processo de assinatura, pode enviar o documento PDF na mesma requisição: em Base64 com file, ou em binário (por meio de uma URL assinada com PUT) usando compress. Se você quiser que a assinatura e a solicitação de anexos façam parte de um modelo de fluxo pré-salvo, ele deve ser configurado previamente com nossa equipe de suporte; depois de criado, você o referencia pelo seu id no campo document.

info

Antes de integrar este endpoint, talvez seja necessário consultar como definir as posições de assinatura e as configurações de validação de identidade.

---

Autenticação

Inclua sua chave privada no cabeçalho Authorization.

Authorization: prk_xxx...

---

Parâmetros de criação

info

• Os campos file, compress e document são mutuamente exclusivos: você pode enviar no máximo um. Se não enviar nenhum, é criado um processo de coleta de anexos sem assinatura (nenhum documento é gerado) e, nesse caso, name também não é obrigatório.
• Cada objeto signProfile deve incluir exatamente um entre type, label ou position (mutuamente exclusivos e um obrigatório), mesmo em processos somente de anexos, sem assinatura.

Nome	Tipo	Descrição
email	String obrigatório	Endereço de e-mail do criador do processo.
document	String condicional	Id de um modelo de fluxo pré-salvo (criado previamente com a equipe de suporte) usado para criar o processo.
name	String condicional	Nome do documento a ser assinado. Obrigatório apenas se o processo incluir um documento (file, compress ou document). Em um processo de coleta de anexos sem assinatura, não é necessário enviá-lo.
packageName	String obrigatório	Nome da pasta que conterá os anexos e o documento a ser assinado (se incluído).
message	String opcional	Mensagem que será incluída no corpo do e-mail de notificação enviado aos signatários ou aprovadores. Se não for enviada, a Auco usa um valor padrão.
subject	String opcional	Assunto do e-mail de notificação enviado aos signatários ou aprovadores. Se não for enviado, a Auco usa um valor padrão.
file	String condicional	Se você quiser enviar o documento na mesma requisição, envie o arquivo PDF em formato Base64 neste parâmetro. (Apenas para arquivos pequenos)
compress	Boolean condicional	Se o arquivo PDF a ser enviado for muito grande, recomenda-se não enviar o parâmetro file; use compress: true. O serviço retornará uma URL assinada para enviar o arquivo PDF em formato binário por meio de uma requisição PUT.
folder	String condicional	Se você quiser salvar este processo em uma pasta específica, informe aqui o caminho dessa pasta. A pasta deve existir e pertencer ao criador do processo.
remember	Number condicional	Ativa lembretes automáticos com o intervalo de tempo (em horas) entre cada notificação. Deve ser múltiplo de 3.
expiredDate	Date opcional	Data de expiração do documento. Deve ser pelo menos 3 dias após a data de criação do processo e deve ser enviada no formato JSON Date.
camera	Boolean opcional	Indica se a validação por foto é exigida. O padrão é false.
otpCode	Boolean opcional	Indica se a validação por código OTP é exigida. O padrão é false.
options	Object opcional	Especifica as configurações de validação de identidade.
signProfile	Array obrigatório	Lista de objetos com as informações de cada signatário ou aprovador para notificação e assinatura.
signProfile[x].name	String obrigatório	Nome do usuário dos anexos.
signProfile[x].email	String obrigatório	Endereço de e-mail do usuário dos anexos.
signProfile[x].phone	String obrigatório	Número de telefone do usuário dos anexos.
signProfile[x].role	String condicional	Define o papel do participante; pode ser 'APPROVER' ou 'SIGNER'.
signProfile[x].order	String condicional	Define a ordem em que ocorrerá o processo de notificação para assinatura ou aprovação.
signProfile[x].label	Boolean condicional	Indica se o posicionamento das assinaturas será feito por meio de etiquetas (labels) no PDF.
signProfile[x].position	Array condicional	Posições de assinatura deste signatário em cada página. As posições de assinatura podem ser pré-carregadas em modelos. Obtenha mais informações na documentação.
signProfile[x].type	String condicional	Identificador do tipo de signatário se estiver pré-salvo em um modelo, por exemplo, 'co-signer'.
signProfile[x].options	Object opcional	Permite definir validações personalizadas para um signatário específico. Se você quiser aplicar validações individuais por signatário, este parâmetro aceita os mesmos campos que o options global. Você pode combinar validações globais e individuais, aplicando as globais por padrão e as individuais onde for necessário um tratamento especial.
signProfile[x].camera	Boolean opcional	Para ter validações individuais por signatário e exigir validação por foto, defina este parâmetro como true. O padrão é false.
signProfile[x].otpCode	Boolean opcional	Para ter validações individuais por signatário e exigir validação por OTP, defina este parâmetro como true. O padrão é false.
signProfile[x].files	Array obrigatório	Lista de arquivos anexos que serão solicitados ao signatário.
signProfile[x].files[x].name	String obrigatório	Nome do arquivo anexo.
signProfile[x].files[x].optional	Boolean opcional	Se algum arquivo anexo for opcional, envie este parâmetro como true. O padrão é false.

A Auco sempre notifica em um processo de anexos

Diferentemente de POST /document/many e POST /document/upload, a notificação não pode ser desativada aqui: a Auco escreve a cada participante para solicitar seus arquivos. Enviar notification na raiz ou dentro de signProfile[x] retorna um erro — no caso do signatário, SIGNER_NOTIFICATION_NOT_SUPPORTED.

---

🧪 Exemplos de uso

dica

Você pode copiar qualquer um dos exemplos de acordo com a sua linguagem preferida.

Somente coleta de anexos (sem documento nem assinatura)

dica

Nenhum file, compress, document ou name é enviado: o processo apenas solicita anexos aos participantes.

curl

curl --location 'https://api.auco.ai/v1.5/ext/package/upload' \
--header 'Authorization: prk_prk_tuLlavePrivada' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "packageName": "Adjuntos sin firma",
    "signProfile": [
        {
            "type": "anexador1",
            "name": "Nombre Anexador 1",
            "email": "example@auco.ai",
            "phone": "+573000000000",
            "files": [
                {
                    "name": "cedula de ciudadanía"
                },
                {
                    "name": "hoja de vida",
                    "optional": true
                }
            ]
        }
    ]
}'

Python

import requests
import json

url = "https://api.auco.ai/v1.5/ext/package/upload"

payload = json.dumps({
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "packageName": "Adjuntos sin firma",
  "signProfile": [
    {
      "type": "anexador1",
      "name": "Nombre Anexador 1",
      "email": "example@auco.ai",
      "phone": "+573000000000",
      "files": [
        {
          "name": "cedula de ciudadanía"
        },
        {
          "name": "hoja de vida",
          "optional": True
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_prk_tuLlavePrivada',
  'Content-Type': 'application/json'
}

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

print(response.text)

Node.js

const axios = require('axios');
let data = JSON.stringify({
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  packageName: 'Adjuntos sin firma',
  signProfile: [
    {
      type: 'anexador1',
      name: 'Nombre Anexador 1',
      email: 'example@auco.ai',
      phone: '+573000000000',
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
          optional: true,
        },
      ],
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/package/upload',
  headers: {
    Authorization: 'prk_tuLlavePrivada',
    'Content-Type': 'application/json',
  },
  data: data,
};

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

---

Anexos opcionais com assinatura de documento (PDF em Base64)

curl

curl --location 'https://api.auco.ai/v1.5/ext/package/upload' \
--header 'Authorization: prk_prk_tuLlavePrivada' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Contratación de prueba upload 1",
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "packageName": "Adjuntos api prueba",
    "file": Base64,
    "signProfile": [
        {
            "name": "Nombre Firmante 1",
            "email": "example@auco.ai",
            "phone": "+573000000000",
            "position": [
                {
                    "page": 1,
                    "x": 0.5854166461564629,
                    "y": 0.8034861200774693,
                    "w": 100,
                    "h": 50
                }
            ],
            "files": [
                {
                    "name": "cedula de ciudadanía"
                },
                {
                    "name": "hoja de vida"
                },
                {
                    "name": "pasaporte",
                    "optional": true
                }
            ]
        }
    ],
}'

Python

import requests
import json

url = "https://api.auco.ai/v1.5/ext/package/upload"

payload = json.dumps({
  "name": "Contratación de prueba upload 1",
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "packageName": "Adjuntos api prueba",
  "file": Base64,
  "signProfile": [
    {
      "name": "Nombre Firmante 1",
      "email": "example@auco.ai",
      "phone": "+573000000000",
      "position": [
        {
          "page": 1,
          "x": 0.5854166461564629,
          "y": 0.8034861200774693,
          "w": 100,
          "h": 50
        }
      ],
      "files": [
        {
          "name": "cedula de ciudadanía"
        },
        {
          "name": "hoja de vida"
        },
        {
          "name": "pasaporte",
          "optional": True
        }
      ]
    }
  ],
})
headers = {
  'Authorization': 'prk_prk_tuLlavePrivada',
  'Content-Type': 'application/json'
}

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

print(response.text)

Node.js

const axios = require('axios');
let data = JSON.stringify({
  name: 'Contratación de prueba upload 1',
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  packageName: 'Adjuntos api prueba',
  file: Base64,
  signProfile: [
    {
      name: 'Nombre Firmante 1',
      email: 'example@auco.ai',
      phone: '+573000000000',
      position: [
        {
          page: 1,
          x: 0.5854166461564629,
          y: 0.8034861200774693,
          w: 100,
          h: 50,
        },
      ],
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
        },
        {
          name: 'pasaporte',
          optional: true,
        },
      ],
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/package/upload',
  headers: {
    Authorization: 'prk_tuLlavePrivada',
    'Content-Type': 'application/json',
  },
  data: data,
};

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

---

Anexos opcionais com assinatura de documento (PDF compress e validações individuais)

curl

curl --location 'https://api.auco.ai/v1.5/ext/package/upload' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba de Anexos Compress y validaciones individuales",
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "packageName": "Adjuntos api prueba 2",
    "signProfile": [
        {
            "type": "firmante1",
            "name": "Nombre Firmante 1",
            "email": "example @auco.ai",
            "camera": true,
            "otpCode": true,
            "options": {
                "camera": "identification",
                "whatsapp": true,
                "otpCode": "email"
            },
            "phone": "+573000000000",
            "files": [
                {
                    "name": "cedula de ciudadanía"
                },
                {
                    "name": "hoja de vida"
                },
                {
                    "name": "pasaporte",
                    "optional": true
                }
            ]
        },
        {
            "type": "firmante2",
            "name": "Nombre Firmante 2",
            "email": "example2@auco.ai",
            "phone": "+573000000000",
            "otpCode": true,
            "options": {
                "otpCode": "email"
            },
            "files": [
                {
                    "name": "certificado"
                }
            ]
        }
    ],
    "compress": true
}'

Python

import requests
import json

url = "https://api.auco.ai/v1.5/ext/package/upload"

payload = json.dumps({
  "name": "Prueba de Anexos Compress y validaciones individuales",
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "packageName": "Adjuntos api prueba 2",
  "signProfile": [
    {
      "type": "firmante1",
      "name": "Nombre Firmante 1",
      "email": "example @auco.ai",
      "camera": True,
      "otpCode": True,
      "options": {
        "camera": "identification",
        "whatsapp": True,
        "otpCode": "email"
      },
      "phone": "+573000000000",
      "files": [
        {
          "name": "cedula de ciudadanía"
        },
        {
          "name": "hoja de vida"
        },
        {
          "name": "pasaporte",
          "optional": True
        }
      ]
    },
    {
      "type": "firmante2",
      "name": "Nombre Firmante 2",
      "email": "example2@auco.ai",
      "phone": "+573000000000",
      "otpCode": True,
      "options": {
        "otpCode": "email"
      },
      "files": [
        {
          "name": "certificado"
        }
      ]
    }
  ],
  "compress": True
})
headers = {
  'Authorization': 'prk_private_key_company',
  'Content-Type': 'application/json'
}

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

print(response.text)

Node.js

const axios = require('axios');
let data = JSON.stringify({
  name: 'Prueba de Anexos Compress y validaciones individuales',
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  packageName: 'Adjuntos api prueba 2',
  signProfile: [
    {
      type: 'firmante1',
      name: 'Nombre Firmante 1',
      email: 'example @auco.ai',
      camera: true,
      otpCode: true,
      options: {
        camera: 'identification',
        whatsapp: true,
        otpCode: 'email',
      },
      phone: '+573000000000',
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
        },
        {
          name: 'pasaporte',
          optional: true,
        },
      ],
    },
    {
      type: 'firmante2',
      name: 'Nombre Firmante 2',
      email: 'example2@auco.ai',
      phone: '+573000000000',
      otpCode: true,
      options: {
        otpCode: 'email',
      },
      files: [
        {
          name: 'certificado',
        },
      ],
    },
  ],
  compress: true,
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/package/upload',
  headers: {
    Authorization: 'prk_private_key_company',
    'Content-Type': 'application/json',
  },
  data: data,
};

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

---

📥 Exemplos de respostas

🔹 Envio do PDF em Base64 usando o atributo 'file'

{
  "package": "PROCESSID",
  "code": "DOCUMENTCODE"
}

🔹 Processo somente de anexos (sem documento)

info

Como nenhum documento é criado, a resposta inclui apenas o package.

{
  "package": "PROCESSID"
}

🔸 Envio do atributo 'compress'

info

A URL assinada fornecida na resposta é de uso único e ficará disponível por apenas 5 segundos. Ela deve ser usada para enviar o documento PDF em formato binário por meio de uma requisição HTTP PUT.

{
  "package": "PROCESSID",
  "code": "DOCUMENTCODE",
  "url": "signed_url"
}

---

⚠️ Respostas de erro

Código	Descrição
400	Parâmetros ausentes, ou algumas validações não atendem às condições de aplicabilidade
401	Autenticação inválida ou ausente