Criar um pacote de assinatura

POST/document/manychave privadaprk_

Este serviço permite gerar um pacote de documentos a partir de um modelo da Auco ou de um arquivo PDF. Concluído o processo, você receberá cada documento com seu próprio certificado de assinatura.

info

Antes de integrar este endpoint, talvez você precise ver como definir as posições das assinaturas e as configurações de validação de identidade no nível do pacote.

aviso

O array documents deve conter pelo menos 2 elementos. Se você precisa de apenas um documento, use o endpoint POST /document/upload.

Passos para criar um pacote de documentos por meio de um modelo automatizado:

Consulte os modelos ou documentos personalizados disponíveis.
Obtenha o _id do documento base.
Consulte as variáveis necessárias do documento selecionado.
Monte e envie a requisição de criação.

info

Se você quiser fazer isso usando um PDF, não é necessário enviar o arquivo na requisição inicial. Ao final, será retornada uma URL assinada para cada documento do pacote.

A seguir estão os parâmetros necessários para este serviço, juntamente com exemplos e possíveis respostas do sistema.

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.
`package`	String opcional	Identificador de um pacote previamente colocado em edição. Enviá-lo sobrescreve esse pacote em vez de criar um novo, mantendo seu identificador. Reenvie o payload completo: tudo o que você omitir é removido. Saiba mais
`document`	String condicional	ID do documento personalizado ou do modelo da Auco. Obrigatório somente se você quiser usar um modelo.
`name`	String obrigatório	Nome do processo de assinatura do documento. Obrigatório se o processo incluir assinatura de documentos.
`message`	String opcional	Mensagem que será enviada no corpo do e-mail que notifica os signatários ou aprovadores do documento.
`subject`	String opcional	Assunto com o qual o e-mail de notificação será enviado aos signatários ou aprovadores.
`folder`	String condicional	Se quiser salvar este processo em uma pasta específica, informe o caminho aqui. 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 é enviada no formato Date do JSON.
`camera`	Boolean opcional	Indica se a validação por foto é obrigatória. O padrão é `false`.
`otpCode`	Boolean opcional	Indica se a validação por código OTP é obrigatória. O padrão é `false`.
`options`	Object opcional	Especifica as configurações de validação de identidade. Veja 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`. Os signatários que a Auco não notifica recebem um `id` na resposta, agrupado por e-mail em todos os documentos, para que o integrador possa levá-los a assinar por conta própria.
`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. Aplica-se a todo o pacote.
`data`	Array condicional	Contém todos os dados exigidos pelo modelo para gerar o documento. Obrigatório somente se você usar um modelo.
`data[x].key`	String obrigatório	Nome do parâmetro registrado no modelo.
`data[x].value`	String obrigatório	Valor atribuído ao parâmetro.
`documents` *	Array obrigatório	Lista de objetos, cada um representando um documento do pacote.
`documents[0].name`	String obrigatório	Nome do documento.
`documents[0].readers`	Array opcional	Lista de objetos que definem participantes que não fazem parte do processo de assinatura, mas devem acompanhar cada etapa dele.
`documents[0].readers[x].name`	String obrigatório	Nome do leitor.
`documents[0].readers[x].email`	String obrigatório	Endereço de e-mail do leitor.
`documents[0].signProfile`	Array obrigatório	Lista de objetos com as informações de cada signatário ou aprovador para notificação e assinatura.
`documents[0].signProfile[x].name`	String obrigatório	Nome do signatário.
`documents[0].signProfile[x].email`	String obrigatório	Endereço de e-mail do signatário. É o que a Auco usa para relacioná-lo a cada documento do pacote, por isso é obrigatório mesmo quando você o notifica por WhatsApp. Omiti-lo retorna `SIGNER_EMAIL_REQUIRED`.
`documents[0].signProfile[x].phone`	String opcional	Número de telefone do signatário, com código do país. Obrigatório se o pacote usar o WhatsApp como canal.
`documents[0].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 nos modelos. Veja mais em como definir as posições das assinaturas.
`documents[0].signProfile[x].type`	Array condicional	Nome usado para identificar o tipo de signatário se estiver pré-salvo em um modelo, por exemplo: `'co-signer'`.
`documents[0].signProfile[x].label`	Boolean condicional	Indica se o posicionamento das assinaturas será feito por meio de rótulos no PDF.
`documents[0].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`. Se o mesmo e-mail aparecer em vários documentos com valores diferentes, `false` prevalece. Aplica-se apenas a documentos PDF; nos documentos de modelo, o indicador por signatário é definido no `signatureProfile` do modelo.

As validações de identidade em pacotes são globais

Neste serviço, a validação de identidade e o canal de assinatura são configurados uma única vez para todo o pacote, usando camera, otpCode e options na raiz da requisição, e valem igualmente para todos os participantes.

A criação de pacotes não oferece suporte a validações de identidade nem à escolha de canal por participante. Enviar camera, otpCode ou options dentro de signProfile[x] retorna o erro SIGNER_VALIDATIONS_NOT_SUPPORTED. Se você precisa de validações diferentes por participante, crie processos separados com POST /document/upload.

Um pacote não tem assinatura sequencial nem papéis

Todos os participantes de um pacote são notificados ao mesmo tempo: não há turnos nem etapas de aprovação. Enviar role ou order dentro de signProfile[x] retorna o erro SIGNER_SEQUENCE_NOT_SUPPORTED.

Se você precisa que alguns participantes assinem antes de outros, ou que alguém aprove antes de a assinatura começar, crie processos separados com POST /document/upload, que oferece suporte a order e role.

🧪 Exemplos de uso

dica

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

Os endereços de e-mail e os números de telefone entre os signatários não devem se repetir.
Os leitores receberão notificações a cada atualização do processo de assinatura.
Formato de data: 'DD/MM/YYYY'
Os números de telefone devem incluir o código do país, por exemplo: +57, +1, +52...

Pacote de documentos via PDF

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/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://api.auco.ai/v1.5/ext/document/many"

payload = json.dumps({
  "name": "Contract package",
  "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: 'Contract package',
  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://api.auco.ai/v1.5/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);
  });

Pacote de documentos via modelos personalizados

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Contract package",
    "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://api.auco.ai/v1.5/ext/document/many"

payload = json.dumps({
  "name": "Contract package",
  "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: 'Contract package',
  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://api.auco.ai/v1.5/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);
  });

📥 Exemplos de respostas

Pacote de documentos via PDF

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [{ "name": "Firmante 1", "email": "example1@auco.ai" }]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "name": "Firmante 1", "email": "example2@auco.ai" }]
    }
  ]
}

info

A URL assinada fornecida na resposta só estará disponível por 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.

Via modelos personalizados

{
  "id": "packageId",
  "documents": [
    {
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [{ "name": "Firmante 1", "email": "example1@auco.ai" }]
    },
    {
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "name": "Firmante 1", "email": "example2@auco.ai" }]
    }
  ]
}

🔹 Signatários que a Auco não notifica

Um signatário é silenciado quando sua notification efetiva é false: a dele, se tiver uma, ou do contrário a global. signProfile sempre volta na resposta; o que muda é que os signatários silenciados carregam um id e os que a Auco notifica não, porque o acesso deles é gerado quando o e-mail é enviado.

Este exemplo desativa a notificação para todo o pacote e a reativa apenas para example2@auco.ai:

{
  "name": "Contract package",
  "email": "example@auco.ai",
  "notification": false,
  "documents": [
    {
      "name": "Documento 1",
      "signProfile": [
        { "type": "solicitante", "name": "Firmante 1", "email": "example1@auco.ai" },
        { "type": "aprobador", "name": "Firmante 2", "email": "example2@auco.ai", "notification": true }
      ]
    },
    {
      "name": "Documento 2",
      "signProfile": [
        { "type": "solicitante", "name": "Firmante 1", "email": "example1@auco.ai" }
      ]
    }
  ]
}

Firmante 1 aparece nos dois documentos, então recebe o mesmo id em cada um: é uma única pessoa dentro do pacote. Firmante 2 não tem id porque a Auco cuida dele.

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [
        { "id": "0Q", "name": "Firmante 1", "email": "example1@auco.ai" },
        { "name": "Firmante 2", "email": "example2@auco.ai" }
      ]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "id": "0Q", "name": "Firmante 1", "email": "example1@auco.ai" }]
    }
  ]
}

Campo	Tipo	Descrição
`documents[x].signProfile`	Array	Lista de signatários do documento.
`documents[x].signProfile[y].id`	String	Identificador do signatário dentro do pacote. Presente apenas quando a Auco não o notifica; regenerado se você sobrescrever o pacote.
`documents[x].signProfile[y].name`	String	Nome do signatário.
`documents[x].signProfile[y].email`	String	E-mail do signatário.

⚠️ Respostas de erro

Código	Descrição
400	Parâmetros ausentes, ou uma ou mais validações não atendem às condições de aplicabilidade.
400	`DOCUMENTS_MIN_TWO` — O array `documents` deve ter pelo menos 2 elementos. Use `/document/upload` para um único documento.
401	Autenticação inválida ou ausente.

Passos para criar um pacote de documentos por meio de um modelo automatizado:​

Autenticação​

Parâmetros de criação​

🧪 Exemplos de uso​

Pacote de documentos via PDF​

Pacote de documentos via modelos personalizados​

📥 Exemplos de respostas​

Pacote de documentos via PDF​

Via modelos personalizados​

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

⚠️ Respostas de erro​

Passos para criar um pacote de documentos por meio de um modelo automatizado:

Autenticação

Parâmetros de criação

🧪 Exemplos de uso

Pacote de documentos via PDF

Pacote de documentos via modelos personalizados

📥 Exemplos de respostas

Pacote de documentos via PDF

Via modelos personalizados

🔹 Signatários que a Auco não notifica

⚠️ Respostas de erro