Pré-preenchimento de dados do documento

POST/document/prebuildchave privadaprk_

Este serviço permite criar um processo de assinatura a partir de um documento personalizado, pré-preenchendo apenas parte das informações e enviando-o a um destinatário que completará os dados restantes. Diferentemente da criação de documento, em que todos os valores necessários para gerar o documento são enviados de uma só vez, aqui o processo é criado no estado em andamento com os campos pré-preenchidos e aguarda o destinatário preencher as informações pendentes.

É útil quando uma das partes (por exemplo, sua organização) já conhece alguns dados do documento e deseja deixá-los preenchidos, enquanto a outra parte (o destinatário) deve fornecer o restante antes de assinar.

info

Os campos que podem ser pré-preenchidos são definidos na configuração do documento personalizado. Antes de integrar este endpoint, talvez você precise consultar as variáveis do documento e, se aplicável, como definir as posições de assinatura e as configurações de validação de identidade.

Etapas para pré-preencher um documento:

1. Consultar o documento personalizado: identifique o documento personalizado que deseja usar e obtenha o _id dele.
2. Identificar as variáveis pré-preenchíveis: consulte as variáveis do documento para saber quais você pode pré-preencher.
3. Montar o array preBuild: monte a lista de pares key / value com os dados que deseja deixar preenchidos.
4. Enviar a requisição: faça a requisição (POST) indicando o destinatário (emailTo) que completará as informações restantes.

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

---

Autenticação

Inclua sua chave privada no cabeçalho Authorization.

Authorization: prk_xxx...

---

Parâmetros de pré-preenchimento

Nome	Tipo	Descrição
email	String obrigatório	E-mail do criador do processo.
name	String obrigatório	Nome do processo do documento.
document	String obrigatório	ID do documento personalizado a partir do qual o processo é criado.
preBuild	Array obrigatório	Lista de objetos com os dados pré-preenchidos no documento. Somente as variáveis habilitadas para pré-preenchimento na configuração do documento são aceitas.
preBuild[x].key	String obrigatório	Nome da variável registrada no documento.
preBuild[x].value	String obrigatório	Valor atribuído à variável.
sign	Boolean obrigatório	Define se o processo será feito por assinatura. Se false, o documento será enviado por e-mail para impressão.
notification	Boolean obrigatório	Define se o destinatário (emailTo) é notificado assim que o processo é criado, para que possa completar as informações.
emailTo	String obrigatório	E-mail do destinatário que deve completar os dados restantes do documento.
folder	String condicional	Caminho da pasta onde o processo será salvo. A pasta deve existir e pertencer ao criador do processo.
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ções da validação de identidade. Saiba mais
expiredDate	Date opcional	Data de expiração do documento. Deve ser superior a 3 dias a partir da data de criação e é enviada no formato Date do JSON.

---

🧪 Exemplos de uso

dica

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

• Em preBuild, envie apenas as variáveis que deseja pré-preencher; o destinatário completará o restante.
• Os números de telefone devem incluir o código do país, por exemplo: +57, +1, +52...

Pré-preenchimento de dados

curl

curl --location 'https://api.auco.ai/v1.5/ext/document/prebuild' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "example@auco.ai",
    "name": "Employment contract - Juan Pérez",
    "document": "64823dc5ce28a265e02d68f3",
    "sign": true,
    "notification": true,
    "emailTo": "juan.perez@example.com",
    "preBuild": [
        {
            "key": "company_name",
            "value": "Auco SAS"
        },
        {
            "key": "position",
            "value": "Backend Developer"
        }
    ]
}'

Python

import requests
import json

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

payload = json.dumps({
  "email": "example@auco.ai",
  "name": "Employment contract - Juan Pérez",
  "document": "64823dc5ce28a265e02d68f3",
  "sign": True,
  "notification": True,
  "emailTo": "juan.perez@example.com",
  "preBuild": [
    {
      "key": "company_name",
      "value": "Auco SAS"
    },
    {
      "key": "position",
      "value": "Backend Developer"
    }
  ]
})
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({
  email: 'example@auco.ai',
  name: 'Employment contract - Juan Pérez',
  document: '64823dc5ce28a265e02d68f3',
  sign: true,
  notification: true,
  emailTo: 'juan.perez@example.com',
  preBuild: [
    {
      key: 'company_name',
      value: 'Auco SAS',
    },
    {
      key: 'position',
      value: 'Backend Developer',
    },
  ],
});

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

Criação do processo

{
  "document": "DOCUMENTCODE"
}

---

⚠️ Respostas de erro

Código	Descrição
400	Parâmetros ausentes, o documento não existe ou uma variável não corresponde à configuração do documento
401	Autenticação inválida ou ausente