Atualização de modelo

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

PUT/templatechave privadaprk_

---

Autenticação

Inclua sua chave privada no cabeçalho Authorization.

Authorization: prk_xxx...

---

Parâmetros de atualização

Nome	Tipo	Descrição
id	String obrigatório	Identificador do modelo.
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 o preenchimento automático prévio.

Envie o modelo completo

O PUT /template valida o corpo da mesma forma que o POST /template: name, config, sign e signatureProfile são obrigatórios mesmo que não mudem, e a API responde 400 se algum estiver ausente. O mais seguro é partir do que o GET /template?id= retorna, alterar o que precisar e enviá-lo de volta sem urls, que a API não aceita na escrita.

description é mantida se você não a enviar

Omitir description no PUT não apaga a descrição que o modelo já tem: a anterior permanece. Para alterá-la, envie o novo texto — com até 500 caracteres, ou a API responde 400.

Uma descrição salva não pode ser apagada

Hoje não há como deixar um modelo sem descrição depois que ele passa a ter uma: a validação rejeita tanto a string vazia ("") quanto null, e omitir o campo mantém o valor anterior. Se você precisa que o texto deixe de aparecer, substitua-o pelo texto correto.

Exemplos de atualização

curl

curl -X PUT https://api.auco.ai/v1.5/ext/template \
  -H "Content-Type: application/json" \
  -H "Authorization: prk_private_key_company" \
  -d '{
    "id": "64823dc5ce28a265e02d68f3",
    "name": "Modificação das variáveis do documento de teste",
    "description": "Contrato de serviço com um único signatário, para a equipe de vendas",
    "config": [
      {
        "name": "new_question",
        "type": "name",
        "description": "Exemplo de nova pergunta"
      },
      {
        "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 nacional de identidade",
            "value": "id_card"
          },
          {
            "name": "Documento de identidade estrangeiro",
            "value": "foreign_id"
          }
        ]
      },
      {
        "description": "Informe o número do documento nacional de identidade 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 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",
      "new_question"
    ],
    "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 = {
    "id": "64823dc5ce28a265e02d68f3",
    "name": "Modificação das variáveis do documento de teste",
    "description": "Contrato de serviço com um único signatário, para a equipe de vendas",
    "config": [
        {
            "name": "new_question",
            "type": "name",
            "description": "Exemplo de nova pergunta"
        },
        {
            "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 nacional de identidade",
                    "value": "id_card"
                },
                {
                    "name": "Documento de identidade estrangeiro",
                    "value": "foreign_id"
                }
            ]
        },
        {
            "description": "Informe o número do documento nacional de identidade 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 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",
        "new_question"
    ],
    "signatureProfile": [
        {
            "email": "client_email",
            "phone": "client_phone",
            "identification": "client_id_card|client_foreign_id",
            "name": "client_name",
            "type": "client"
        }
    ]
}

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

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

        result = response.json()
        print("Template updated successfully!")
        print(f"Mask URL: {result['urls']['mask']}")
        print(f"Complete URL: {result['urls']['complete']}")

        return result

    except requests.exceptions.RequestException as error:
        print(f"Error updating template: {error.response.json() if hasattr(error, 'response') else error}")

if __name__ == "__main__":
    update_template()

Node.js

const axios = require('axios');

const templateData = {
  id: '64823dc5ce28a265e02d68f3',
  name: 'Modificação das variáveis do documento de teste',
  description: 'Contrato de serviço com um único signatário, para a equipe de vendas',
  config: [
    {
      name: 'new_question',
      type: 'name',
      description: 'Exemplo de nova pergunta',
    },
    {
      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 nacional de identidade',
          value: 'id_card',
        },
        {
          name: 'Documento de identidade estrangeiro',
          value: 'foreign_id',
        },
      ],
    },
    {
      description: 'Informe o número do documento nacional de identidade 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 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',
    'new_question',
  ],
  signatureProfile: [
    {
      email: 'client_email',
      phone: 'client_phone',
      identification: 'client_id_card|client_foreign_id',
      name: 'client_name',
      type: 'client',
    },
  ],
};

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

    console.log('Template updated successfully!');
    console.log('Mask URL:', response.data.urls.mask);
    console.log('Complete URL:', response.data.urls.complete);

    return response.data;
  } catch (error) {
    console.error('Error updating template:', error.response?.data || error.message);
  }
}

updateTemplate();

Exemplo de resposta

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

Envio do HTML completo e do HTML máscara:

Você precisará enviar novamente os arquivos HTML. Na resposta do serviço de atualização, você encontrará duas URLs assinadas, uma para cada HTML. Elas têm uma vida útil de 120 segundos: depois disso, deixam de ser válidas. Deixe os arquivos HTML completo e HTML máscara prontos antes de atualizar o modelo e envie cada um, como está, em uma requisição PUT para a sua URL.

Envie 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 envio é 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):
    """
    Uploads HTML files to the signed URLs

    Args:
        mask_url (str): Signed URL for the HTML Mask
        complete_url (str): Signed URL for the HTML Complete
    """
    try:
        # Read HTML files
        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'}

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

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

    except requests.exceptions.RequestException as error:
        print(f"Error uploading: {error}")

# Usage from the previous response
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');

/**
 * Uploads HTML files to the signed URLs
 * @param {string} maskUrl - Signed URL for the HTML Mask
 * @param {string} completeUrl - Signed URL for the HTML Complete
 */
async function uploadHtmlFiles(maskUrl, completeUrl) {
  try {
    // Read HTML files
    const maskHtml = fs.readFileSync('mask.html');
    const completeHtml = fs.readFileSync('complete.html');

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

    // Upload Mask HTML
    await axios.put(maskUrl, maskHtml, { headers });
    console.log('Mask HTML uploaded successfully');

    // Upload Complete HTML
    await axios.put(completeUrl, completeHtml, { headers });
    console.log('Complete HTML uploaded successfully');
  } catch (error) {
    console.error('Error uploading files:', error.message);
  }
}

// Usage from the previous response
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 o PUT /template novamente: cada chamada retorna novas URLs.

Pule o envio se o HTML não mudou

Se você está atualizando apenas config, sign ou signatureProfile e o HTML não mudou, pode ignorar as URLs retornadas e pular o envio por completo. O servidor manterá os HTMLs da versão anterior.

---

⚠️ Respostas de erro

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

Código	Descrição
400	Corpo inválido ou modelo não encontrado: DOCUMENT_NOT_FOUND (o id não corresponde a um modelo da sua organização), 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 falha, por exemplo "signatureProfile" 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.

Modelos anteriores à validação de signatários

A validação de email e phone no signatureProfile é mais recente que muitos modelos. Um modelo que ainda é preenchido sem problemas pode ser rejeitado pelo PUT com PROFILE_FIELD_TYPE_INVALID, quase sempre porque o e-mail do signatário é solicitado com uma pergunta text. Altere o tipo dessa pergunta para email no mesmo PUT.