Envio de documento

POST/document/uploadchave privadaprk_

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

info

Se você quiser incluir um processo de assinatura, pode enviar diretamente um documento PDF em formato base64. Se quiser que a solicitação de assinatura e anexos faça parte de um modelo, observe que esse fluxo não pode ser configurado diretamente pelo endpoint; você deve solicitar suporte à nossa equipe.

info

Antes de integrar este endpoint, você pode 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

Nome	Tipo	Descrição
`email`	String obrigatório	Endereço de e-mail do criador do processo.
`code`	String opcional	Código de um documento previamente colocado em edição. Enviá-lo sobrescreve esse processo em vez de criar um novo, mantendo o código dele. Reenvie o payload completo: o que você omitir será removido. Saiba mais
`document`	String condicional	Se você quiser criar o processo a partir de um modelo, deve enviar o ID do modelo neste campo. Para visualizar e obter modelos, acesse esta documentação.
`name`	String obrigatório	Nome do processo de assinatura do documento, somente se o processo de anexos incluir a assinatura do documento.
`message`	String condicional	Mensagem que será incluída no corpo do e-mail que notifica os signatários ou aprovadores do documento. Obrigatório quando algum participante for notificado por e-mail.
`subject`	String condicional	Assunto do e-mail de notificação enviado aos signatários ou aprovadores. Obrigatório quando algum participante for notificado por e-mail.
`file`	String condicional	Se você quiser enviar o documento na mesma requisição, envie o arquivo PDF em Base64 neste parâmetro. (Somente 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`. Assim, o serviço retorna 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 o caminho dessa pasta neste parâmetro. Observe que a pasta deve existir e pertencer ao criador do processo.
`remember`	Number condicional	Parâmetro que ativa lembretes automáticos com o intervalo de tempo (em horas) entre cada notificação.
`expiredDate`	Date opcional	Data de expiração do documento. Deve ser superior a 3 dias após a data de criação do processo e é enviada no formato Date do JSON.
`camera`	Boolean opcional	Este parâmetro indica se a validação por foto é exigida. O padrão é `false`.
`otpCode`	Boolean opcional	Este parâmetro indica se a validação por código OTP é exigida. O padrão é `false`.
`options`	Object opcional	Este parâmetro especifica as configurações de validação de identidade. Saiba mais
`notification`	Boolean opcional	Define se a Auco notifica os participantes assim que o processo é criado. O padrão é `true`. É o valor padrão para todos os signatários; cada um pode substituí-lo com `signProfile[x].notification`.
`targetWebhooks`	Array[String] opcional	Se você tiver vários webhooks, pode enviar o nome do webhook para o qual deseja que as atualizações deste processo sejam notificadas.
`tags`	Array[String] opcional	Se você quiser classificar processos com tags, pode enviar os nomes das tags às quais relacionar o processo (elas devem existir).
`custom`	Object opcional	Objeto livre para enviar parâmetros definidos pelo integrador (por exemplo, identificadores internos ou metadados). A Auco o armazena como está e o repassa nas notificações de webhook e na resposta de `GET /document`, sem interpretar nem validar seu conteúdo.
`readers`	Array opcional	Este parâmetro é uma lista de objetos que define participantes que não fazem parte do processo de assinatura, mas devem poder acompanhar cada fase dele.
`readers[x].name`	String obrigatório	Nome do leitor.
`readers[x].email`	String obrigatório	E-mail do leitor.
`signProfile`	Array obrigatório	Este campo é uma lista de objetos com as informações de cada signatário ou aprovador para sua notificação e assinatura.
`signProfile[x].name`	String obrigatório	Nome do signatário.
`signProfile[x].email`	String obrigatório	E-mail do signatário.
`signProfile[x].phone`	String obrigatório	Número de telefone do signatário.
`signProfile[x].role`	String condicional	Este parâmetro define o papel do participante; pode ser `'APPROVER'` ou `'SIGNER'`.
`signProfile[x].order`	String condicional	Este parâmetro define a ordem em que ocorrerá o processo de notificação para assinatura ou aprovação.
`signProfile[x].label`	Boolean(true) \| String condicional	Parâmetro que indica se o posicionamento das assinaturas será feito por meio de tags no PDF.
`signProfile[x].position`	Array condicional	Neste parâmetro são enviadas as 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	Nome usado para identificar o tipo de signatário, se 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 individualmente por signatário, saiba mais.
`signProfile[x].camera`	Boolean opcional	Se você quiser validações individuais por signatário e exigir validação por foto, envie este parâmetro como `true`. O padrão é `false`.
`signProfile[x].otpCode`	Boolean opcional	Se você quiser validações individuais por signatário e exigir validação por código OTP, envie este parâmetro como `true`. O padrão é `false`.
`signProfile[x].notification`	Boolean opcional	Substitui o `notification` global para este signatário, nos dois sentidos: `false` o silencia mesmo que o global seja `true`, e `true` faz a Auco notificá-lo mesmo que o global seja `false`. Signatários silenciados recebem um `id` na resposta.

🧪 Exemplos de uso

dica

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

Lembre-se de que os endereços de e-mail e números de telefone dos signatários não devem se repetir.
Os leitores receberão notificações a cada atualização do processo de assinatura.

Processo de assinatura com lembretes automáticos (PDF Base64)

Neste caso, os lembretes serão enviados a cada 3 horas.

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/upload' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Documento de prueba",
    "subject": "prueba auco",
    "message": "prueba auco",
    "remember": 3,
    "email": "example@auco.ai",
    "signProfile": [
        {
            "name": "Jhon Firma",
            "email": "example@auco.ai",
            "label": true
        }
    ],
    "readers":[{"email":"example2@auco.ai", "name":"Frimante 1"}],
    "file": Base64
}'

import requests
import json

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

payload = json.dumps({
  "name": "Documento de prueba",
  "subject": "prueba auco",
  "message": "prueba auco",
  "remember": 3,
  "email": "example@auco.ai",
  "signProfile": [
    {
      "name": "Jhon Firma",
      "email": "example@auco.ai",
      "label": True
    }
  ],
  "readers": [
    {
      "email": "example2@auco.ai",
      "name": "Frimante 1"
    }
  ],
  "file": Base64
})
headers = {
  'Authorization': 'prk_private_key_company',
  '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: 'Documento de prueba',
  subject: 'prueba auco',
  message: 'prueba auco',
  remember: 3,
  email: 'example@auco.ai',
  signProfile: [
    {
      name: 'Jhon Firma',
      email: 'example@auco.ai',
      label: true,
    },
  ],
  readers: [
    {
      email: 'eyvasquezt30@gmail.com',
      name: 'Frimante 1',
    },
  ],
  file: Base64,
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/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);
  });

Assinatura de documento com validações individuais (compress - PDF binário)

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/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",
    "signProfile": [
        {
            "type": "firmante1",
            "name": "Nombre Firmante 1",
            "email": "example @auco.ai",
            "camera": true,
            "otpCode": true,
            "options": {
                "camera": "identification",
                "whatsapp": true,
                "otpCode": "email"
            },
            "phone": "+573000000000",
        },
        {
            "type": "firmante2",
            "name": "Nombre Firmante 2",
            "email": "example2@auco.ai",
            "phone": "+573000000000",
            "otpCode": true,
            "options": {
                "otpCode": "email"
            },
        }
    ],
    "compress": true
}'

import requests
import json

url = "https://api.auco.ai/v1.5/ext/document/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",
  "signProfile": [
    {
      "type": "firmante1",
      "name": "Nombre Firmante 1",
      "email": "example @auco.ai",
      "camera": True,
      "otpCode": True,
      "options": {
        "camera": "identification",
        "whatsapp": True,
        "otpCode": "email"
      },
      "phone": "+573000000000",
    },
    {
      "type": "firmante2",
      "name": "Nombre Firmante 2",
      "email": "example2@auco.ai",
      "phone": "+573000000000",
      "otpCode": True,
      "options": {
        "otpCode": "email"
      }
    }
  ],
  "compress": True
})
headers = {
  'Authorization': 'prk_private_key_company',
  '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 de Anexos Compress y validaciones individuales',
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  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: 'whatsapp',
      },
    },
  ],
  compress: true,
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/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 resposta

🔹 Modo normal (sem `compress` ou com `compress: false`)

{
  "document": "ABCDEF1234"
}

Campo	Tipo	Descrição
`document`	String	Código único do documento criado.

🔸 Modo compress (`compress: true`)

info

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

{
  "document": "ABCDEF1234",
  "url": "https://s3.amazonaws.com/...signed-url..."
}

Campo	Tipo	Descrição
`document`	String	Código único do documento criado.
`url`	String	URL S3 pré-assinada para enviar o PDF (expira em 300 s).

🔹 Signatários que a Auco não notifica

A resposta inclui signProfile quando algum signatário é silenciado, isto é, quando o notification efetivo dele é false: o próprio, se ele tiver um, ou, caso contrário, o global. Todo signatário silenciado traz um id que o integrador usa para levá-lo a assinar por conta própria. Os signatários que a Auco notifica aparecem sem id: o acesso deles é gerado quando são notificados.

{
  "document": "ABCDEF1234",
  "signProfile": [
    {
      "id": "abc123",
      "name": "Juan",
      "email": "juan@email.com",
      "phone": "+57300..."
    }
  ]
}

Campo	Tipo	Descrição
`document`	String	Código único do documento criado.
`signProfile`	Array	Lista de signatários do processo.
`signProfile[x].id`	String	Identificador único do signatário.
`signProfile[x].name`	String	Nome do signatário.
`signProfile[x].email`	String	Endereço de e-mail do signatário.
`signProfile[x].phone`	String	Número de telefone do signatário.

dica

Este campo também é incluído no modo compress, junto com a 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

Autenticação​

Parâmetros de criação​

🧪 Exemplos de uso​

Processo de assinatura com lembretes automáticos (PDF Base64)​

Assinatura de documento com validações individuais (compress - PDF binário)​

📥 Exemplos de resposta​

🔹 Modo normal (sem compress ou com compress: false)​

🔸 Modo compress (compress: true)​

🔹 Signatários que a Auco não notifica​

⚠️ Respostas de erro​

Autenticação

Parâmetros de criação

🧪 Exemplos de uso

Processo de assinatura com lembretes automáticos (PDF Base64)

Assinatura de documento com validações individuais (compress - PDF binário)

📥 Exemplos de resposta

🔹 Modo normal (sem `compress` ou com `compress: false`)

🔸 Modo compress (`compress: true`)

🔹 Signatários que a Auco não notifica

⚠️ Respostas de erro