Requisitos fundamentais

Guia completo para criar modelos e/ou documentos automatizados com HTML, JSON e o SDK de geração de documentos.

---

Toda automação requer exatamente 3 arquivos:

Arquivo	Descrição
HTML máscara	O HTML que o usuário vê ao preencher o formulário por meio do SDK
HTML completo	HTML para gerar o PDF final, inclui os espaços para as assinaturas
Objeto JSON	Controla o comportamento, define os signatários e as perguntas

Fluxo geral

O processo sempre começa com a construção do HTML completo. Este documento deve conter espaços editáveis onde o usuário insere as informações. Esse HTML dependerá das variáveis registradas no JSON, em que cada pergunta possui um identificador.

Por exemplo:

1. HTML:

<p>Descrição: <span name="question_1">___________</span></p>

2. Pergunta no JSON:

[
  ...,
{
  "name": "question_1",
  "description": "Informe o nome completo do representante legal da empresa contratante",
  "type": "text"
},
  ...
]

3. O que o usuário vê no final:

---

Configuration

1. Para começar a gerar os arquivos HTML, saiba tudo sobre a criação deles em Configuração do HTML.
2. Para começar a gerar o arquivo JSON, consulte a referência completa em Configuração do JSON — ela cobre os 17 tipos de pergunta, as validações e a lógica condicional.
3. Para modelos que precisam validar um código ou buscar dados pré-preenchidos a partir do seu próprio serviço, consulte Tipo de requisição.

Dicas e boas práticas

1. Nomenclatura consistente: use snake_case descritivo nas perguntas: buyer_name, seller_email.
2. Combine os tipos de campo com a semântica: use identification para os documentos dos signatários (não text ou number), nit para identificações fiscais colombianas, currency para valores monetários, email para e-mails.
3. Validação antecipada: marque as perguntas críticas no array sign.
4. Aproveite as validações: deduza subYears (idade), maxlength, regex, min/max a partir dos próprios requisitos do documento. Veja Propriedades de validação.
5. Convenção de signatários: ancore cada assinatura com <div name="X">, não com id. Se uma assinatura aparecer em vários lugares, repita o mesmo name — veja Posicionamento das assinaturas.
6. Campos automáticos: adicione <span name="signDate"> onde a data da assinatura deve aparecer. Veja Campos automáticos ao concluir a assinatura.
7. Múltiplas identificações: use | em signatureProfile.identification para aceitar vários tipos de documento para um mesmo signatário.
8. Restrições do gerador de PDF: o gerador de PDF da Auco não oferece suporte a flexbox, CSS Grid nem variáveis CSS no HTML completo. Veja Restrições do gerador de PDF.
9. Testes: verifique se cada opção clausula é ocultada/exibida corretamente e se a opção padrão corresponde ao value da configuração.

---

Checklist de validação

Antes de publicar sua automação, verifique:

• Você tem os 3 arquivos (HTML máscara, HTML completo, JSON).
• Cada pergunta no JSON tem name, description e type.
• Todo name no HTML corresponde a uma pergunta no JSON — e vice-versa.
• As perguntas clausula têm um <span name="{name}_{value}"> por opção no HTML.
• O value padrão na configuração de uma clausula corresponde ao span sem o atributo hidden.
• As perguntas com prereq referenciam perguntas do tipo clausula.
• Todo signatário em signatureProfile tem seu <div name="X"> no HTML completo, com X igual ao seu type.
• As perguntas em sign referenciam nomes de perguntas reais.
• As perguntas de identificação dos signatários usam type: "identification", e os NITs usam type: "nit".
• As perguntas check usam um array simples values: [...] (não options).
• O HTML não usa display: flex, CSS Grid nem variáveis CSS.
• Caracteres UTF-8 (ñ, á) são escritos diretamente, não como entidades HTML.
• Se estiver usando preBuild: true, você incluiu preBuildData.

---

Exemplo integrado completo

JSON completo

{
  "name": "Contrato de compra e venda",
  "preBuild": false,
  "sign": ["buyer_name", "buyer_email"],
  "config": [
    {
      "name": "buyer_name",
      "description": "Informe seu nome completo",
      "type": "name"
    },
    {
      "name": "identification_type",
      "description": "Selecione seu tipo de documento de identificação",
      "type": "clausula",
      "value": "id_card",
      "options": [
        { "name": "Documento de identidade nacional", "value": "id_card" },
        { "name": "Documento de identidade estrangeiro", "value": "foreign_id" }
      ]
    },
    {
      "name": "id_card_number",
      "description": "Informe seu número de identificação",
      "type": "number",
      "prereq": [{ "k": "identification_type", "v": "id_card" }]
    },
    {
      "name": "foreign_id_number",
      "description": "Informe o número do seu documento estrangeiro",
      "type": "number",
      "prereq": [{ "k": "identification_type", "v": "foreign_id" }]
    },
    {
      "name": "buyer_email",
      "description": "Informe seu endereço de e-mail",
      "type": "email"
    },
    {
      "name": "buyer_phone",
      "description": "Informe seu número de telefone",
      "type": "phone"
    },
    {
      "name": "transaction_value",
      "description": "Informe o valor total da compra",
      "type": "currency"
    },
    {
      "name": "transaction_date",
      "description": "Selecione a data da transação",
      "type": "date"
    },
    {
      "name": "product_description",
      "description": "Descreva brevemente o produto",
      "type": "text"
    }
  ],
  "signatureProfile": [
    {
      "name": "buyer_name",
      "identification": "id_card_number|foreign_id_number",
      "email": "buyer_email",
      "phone": "buyer_phone",
      "type": "buyer"
    }
  ]
}

HTML máscara

<!DOCTYPE html>
<html lang="pt">
  <head>
    <meta charset="UTF-8" />
    <title>Contrato de compra e venda</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        max-width: 800px;
        margin: 40px auto;
        padding: 20px;
      }
      .section {
        margin-bottom: 30px;
        padding: 15px;
        border: 1px solid #ddd;
        border-radius: 5px;
      }
      h1 {
        text-align: center;
        color: #333;
      }
      label {
        font-weight: bold;
        display: block;
        margin-bottom: 5px;
      }
      span {
        border-bottom: 1px solid #000;
        min-width: 200px;
        display: inline-block;
        padding: 5px;
      }
    </style>
  </head>
  <body>
    <h1>Contrato de compra e venda</h1>

    <div class="section">
      <h2>Informações do comprador</h2>
      <label>Nome completo:</label>
      <span name="buyer_name">___________________</span>

      <label>Tipo de identificação:</label>
      <span name="identification_type_id_card">Documento de identidade</span>
      <span name="identification_type_foreign_id" hidden>Documento estrangeiro</span>

      <label>Número de identificação:</label>
      <span name="id_card_number">___________________</span>
      <span name="foreign_id_number" hidden>___________________</span>

      <label>Endereço de e-mail:</label>
      <span name="buyer_email">___________________</span>

      <label>Telefone de contato:</label>
      <span name="buyer_phone">___________________</span>
    </div>

    <div class="section">
      <h2>Informações da transação</h2>
      <label>Descrição do produto:</label>
      <span name="product_description">___________________</span>

      <label>Valor total:</label>
      <span name="transaction_value">___________________</span>

      <label>Data da transação:</label>
      <span name="transaction_date">___________________</span>
    </div>

    <p style="margin-top: 50px; text-align: center;">Assinatura do comprador: ______________________</p>
  </body>
</html>

HTML completo

<!DOCTYPE html>
<html lang="pt">
  <head>
    <meta charset="UTF-8" />
    <title>Contrato de compra e venda</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        max-width: 800px;
        margin: 40px auto;
        padding: 20px;
      }
      .sign-margin {
        min-height: 100px;
        margin-top: 30px;
        page-break-inside: avoid;
      }
    </style>
  </head>
  <body>
    <h1>Contrato de compra e venda</h1>

    <h2>Informações do comprador</h2>
    <p>
      Nome: <strong><span name="buyer_name">___________________</span></strong>
    </p>
    <p>
      Identificação:
      <strong
        ><span name="id_card_number">___________________</span
        ><span name="foreign_id_number" hidden>___________________</span></strong
      >
    </p>
    <p>
      E-mail: <strong><span name="buyer_email">___________________</span></strong>
    </p>

    <h2>Informações da transação</h2>
    <p>
      Produto: <strong><span name="product_description">___________________</span></strong>
    </p>
    <p>
      Valor: <strong><span name="transaction_value">___________________</span></strong>
    </p>
    <p>
      Data: <strong><span name="transaction_date">___________________</span></strong>
    </p>

    <h2>Assinatura</h2>
    <div name="buyer" class="sign-margin"></div>
  </body>
</html>