Criação de modelo

Este serviço permite criar modelos personalizados que depois poderão ser usados para preencher documentos para assinatura.

POST/templatechave privadaprk_

---

Autenticação

Inclua sua chave privada no cabeçalho Authorization.

Authorization: prk_xxx...

---

Parâmetros de criação

Nome	Tipo	Descrição
name	String obrigatório	Nome da automação.
description	String opcional	Texto que descreve o modelo, com até 500 caracteres.
config	Array obrigatório	Array de perguntas para o usuário. Veja Configuração JSON.
signatureProfile	Array obrigatório	Definição de signatários e aprovadores. Veja Perfis de assinatura.
sign	Array obrigatório	Nomes das perguntas obrigatórias.
preBuild	Boolean opcional	Se true, inclui preenchimento automático.

O limite de description é de 500 caracteres

description é informativa: ela não altera o comportamento do modelo e ajuda sua equipe a reconhecer para que serve cada modelo. Se você não a enviar, o modelo fica sem descrição. Se o texto passar de 500 caracteres, a API responde 400 e não cria o modelo.

GET /template retorna o campo, tanto na lista quanto no detalhe por id.

Exemplos de criação

curl

curl -X POST https://api.auco.ai/v1.5/ext/template \
  -H "Content-Type: application/json" \
  -H "Authorization: prk_private_key_company" \
  -d '{
    "name": "Teste de modificação de variáveis do documento",
    "description": "Contrato de serviço com um único signatário, para a equipe de vendas",
    "config": [
      {
        "name": "client_name",
        "type": "name",
        "description": "Informe o nome do cliente"
      },
      {
        "description": "Selecione o tipo de documento do cliente",
        "name": "client_document_type",
        "type": "clausula",
        "value": "id_card",
        "options": [
          {
            "name": "Documento de identidade nacional",
            "value": "id_card"
          },
          {
            "name": "Documento de identidade de estrangeiro",
            "value": "foreign_id"
          }
        ]
      },
      {
        "description": "Informe o número do documento de identidade nacional do cliente",
        "name": "client_id_card",
        "type": "number",
        "prereq": [
          {
            "k": "client_document_type",
            "v": "id_card"
          }
        ]
      },
      {
        "description": "Informe o número do documento de identidade de estrangeiro do cliente",
        "name": "client_foreign_id",
        "type": "number",
        "prereq": [
          {
            "k": "client_document_type",
            "v": "foreign_id"
          }
        ]
      },
      {
        "name": "client_email",
        "type": "email",
        "description": "Informe o e-mail do cliente"
      },
      {
        "name": "client_phone",
        "type": "phone",
        "description": "Informe o telefone do cliente"
      }
    ],
    "sign": [
      "client_name",
      "client_id_card",
      "client_foreign_id",
      "client_email",
      "client_phone"
    ],
    "signatureProfile": [
      {
        "email": "client_email",
        "phone": "client_phone",
        "identification": "client_id_card|client_foreign_id",
        "name": "client_name",
        "type": "client"
      }
    ]
  }'

Python

import requests
import json

template_data = {
    "name": "Teste de modificação de variáveis do documento",
    "description": "Contrato de serviço com um único signatário, para a equipe de vendas",
    "config": [
        {
            "name": "client_name",
            "type": "name",
            "description": "Informe o nome do cliente"
        },
        {
            "description": "Selecione o tipo de documento do cliente",
            "name": "client_document_type",
            "type": "clausula",
            "value": "id_card",
            "options": [
                {
                    "name": "Documento de identidade nacional",
                    "value": "id_card"
                },
                {
                    "name": "Documento de identidade de estrangeiro",
                    "value": "foreign_id"
                }
            ]
        },
        {
            "description": "Informe o número do documento de identidade nacional do cliente",
            "name": "client_id_card",
            "type": "number",
            "prereq": [
                {
                    "k": "client_document_type",
                    "v": "id_card"
                }
            ]
        },
        {
            "description": "Informe o número do documento de identidade de estrangeiro do cliente",
            "name": "client_foreign_id",
            "type": "number",
            "prereq": [
                {
                    "k": "client_document_type",
                    "v": "foreign_id"
                }
            ]
        },
        {
            "name": "client_email",
            "type": "email",
            "description": "Informe o e-mail do cliente"
        },
        {
            "name": "client_phone",
            "type": "phone",
            "description": "Informe o telefone do cliente"
        }
    ],
    "sign": [
        "client_name",
        "client_id_card",
        "client_foreign_id",
        "client_email",
        "client_phone"
    ],
    "signatureProfile": [
        {
            "email": "client_email",
            "phone": "client_phone",
            "identification": "client_id_card|client_foreign_id",
            "name": "client_name",
            "type": "client"
        }
    ]
}

def create_template():
    url = "https://api.auco.ai/v1.5/ext/template"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "prk_private_key_company"
    }

    try:
        response = requests.post(
            url,
            json=template_data,
            headers=headers
        )
        response.raise_for_status()

        result = response.json()
        print("Modelo criado com sucesso!")
        print(f"ID do modelo: {result['id']}")
        print(f"URL do Mask: {result['urls']['mask']}")
        print(f"URL do Complete: {result['urls']['complete']}")

        return result

    except requests.exceptions.RequestException as error:
        print(f"Erro ao criar o modelo: {error.response.json() if hasattr(error, 'response') else error}")

if __name__ == "__main__":
    create_template()

Node.js

const axios = require('axios');

const templateData = {
  name: 'Teste de modificação de variáveis do documento',
  description: 'Contrato de serviço com um único signatário, para a equipe de vendas',
  config: [
    {
      name: 'client_name',
      type: 'name',
      description: 'Informe o nome do cliente',
    },
    {
      description: 'Selecione o tipo de documento do cliente',
      name: 'client_document_type',
      type: 'clausula',
      value: 'id_card',
      options: [
        {
          name: 'Documento de identidade nacional',
          value: 'id_card',
        },
        {
          name: 'Documento de identidade de estrangeiro',
          value: 'foreign_id',
        },
      ],
    },
    {
      description: 'Informe o número do documento de identidade nacional do cliente',
      name: 'client_id_card',
      type: 'number',
      prereq: [
        {
          k: 'client_document_type',
          v: 'id_card',
        },
      ],
    },
    {
      description: 'Informe o número do documento de identidade de estrangeiro do cliente',
      name: 'client_foreign_id',
      type: 'number',
      prereq: [
        {
          k: 'client_document_type',
          v: 'foreign_id',
        },
      ],
    },
    {
      name: 'client_email',
      type: 'email',
      description: 'Informe o e-mail do cliente',
    },
    {
      name: 'client_phone',
      type: 'phone',
      description: 'Informe o telefone do cliente',
    },
  ],
  sign: ['client_name', 'client_id_card', 'client_foreign_id', 'client_email', 'client_phone'],
  signatureProfile: [
    {
      email: 'client_email',
      phone: 'client_phone',
      identification: 'client_id_card|client_foreign_id',
      name: 'client_name',
      type: 'client',
    },
  ],
};

async function createTemplate() {
  try {
    const response = await axios.post('https://api.auco.ai/v1.5/ext/template', templateData, {
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'prk_private_key_company',
      },
    });

    console.log('Modelo criado com sucesso!');
    console.log('ID do modelo:', response.data.id);
    console.log('URL do Mask:', response.data.urls.mask);
    console.log('URL do Complete:', response.data.urls.complete);

    return response.data;
  } catch (error) {
    console.error('Erro ao criar o modelo:', error.response?.data || error.message);
  }
}

createTemplate();

Exemplo de resposta

{
    "id": "template_id",
    "urls": {
        "mask": "https://signed_url_mask",
        "complete": "https://signed_url_complete"
    }
}

Upload do HTML Complete e do HTML Mask:

Na resposta do serviço de criação, você encontrará duas URLs assinadas, uma para cada HTML. Elas têm validade de 120 segundos: depois disso, deixam de ser válidas. Deixe os arquivos HTML Complete e HTML Mask prontos antes de criar o modelo e envie cada um deles, sem alterações, em uma requisição PUT para a sua URL.

Upload com Content-Type: binary/octet-stream

As URLs são assinadas para esse tipo de conteúdo: se você enviar outro —por exemplo text/html—, o upload é rejeitado. Envie o arquivo sem transformá-lo: no curl use --data-binary, e não -d, que remove as quebras de linha.

curl

# Upload HTML Mask
curl -X PUT https://signed_url_mask \
  -H "Content-Type: binary/octet-stream" \
  --data-binary @mask.html

# Upload HTML Complete
curl -X PUT https://signed_url_complete \
  -H "Content-Type: binary/octet-stream" \
  --data-binary @complete.html

Python

import requests

def upload_html_files(mask_url, complete_url):
    """
    Envia os arquivos HTML para as URLs assinadas

    Args:
        mask_url (str): URL assinada do HTML Mask
        complete_url (str): URL assinada do HTML Complete
    """
    try:
        # Ler os arquivos HTML
        with open('mask.html', 'rb') as f:
            mask_html = f.read()

        with open('complete.html', 'rb') as f:
            complete_html = f.read()

        headers = {'Content-Type': 'binary/octet-stream'}

        # Enviar o HTML Mask
        response_mask = requests.put(mask_url, data=mask_html, headers=headers)
        print(f"HTML Mask enviado: {response_mask.status_code}")

        # Enviar o HTML Complete
        response_complete = requests.put(complete_url, data=complete_html, headers=headers)
        print(f"HTML Complete enviado: {response_complete.status_code}")

    except requests.exceptions.RequestException as error:
        print(f"Erro ao enviar: {error}")

# Uso a partir da resposta anterior
mask_url = "https://signed_url_mask"
complete_url = "https://signed_url_complete"
upload_html_files(mask_url, complete_url)

Node.js

const fs = require('fs');
const axios = require('axios');

/**
 * Envia os arquivos HTML para as URLs assinadas
 * @param {string} maskUrl - URL assinada do HTML Mask
 * @param {string} completeUrl - URL assinada do HTML Complete
 */
async function uploadHtmlFiles(maskUrl, completeUrl) {
  try {
    // Ler os arquivos HTML
    const maskHtml = fs.readFileSync('mask.html');
    const completeHtml = fs.readFileSync('complete.html');

    const headers = { 'Content-Type': 'binary/octet-stream' };

    // Enviar o HTML Mask
    await axios.put(maskUrl, maskHtml, { headers });
    console.log('HTML Mask enviado com sucesso');

    // Enviar o HTML Complete
    await axios.put(completeUrl, completeHtml, { headers });
    console.log('HTML Complete enviado com sucesso');
  } catch (error) {
    console.error('Erro ao enviar os arquivos:', error.message);
  }
}

// Uso a partir da resposta anterior
const maskUrl = 'https://signed_url_mask';
const completeUrl = 'https://signed_url_complete';
uploadHtmlFiles(maskUrl, completeUrl);

As URLs expiram em 120 segundos

Se elas expirarem antes de você enviar os arquivos, chame PUT /template com o id do modelo para obter novas URLs. Não chame POST /template novamente: você criaria outro modelo.

---

⚠️ Respostas de erro

Os erros vêm com o corpo { "message": "..." }.

Código	Descrição
400	Corpo inválido: PAYLOAD_NOT_VALID (o corpo não é JSON), PROFILE_FIELD_NOT_FOUND: <field> (o email ou o phone de um signatário não é uma pergunta de config nem um campo de preFill), PROFILE_FIELD_TYPE_INVALID: <field> must be type <type> (aponta para uma pergunta de outro tipo) ou a mensagem do validador
401	Autenticação inválida ou ausente

A mensagem do validador indica o campo com problema, por exemplo "name" is required, "config[0].maxLength" is not allowed ou "signatureProfile[0].name" must be a string. Veja as regras de cada campo em Configuração JSON.