API de Substituicao de Variaveis - Contrato para Backend

Visao Geral

Endpoints e logica para substituicao de variaveis no HTML dos templates de contrato. Toda substituicao de variaveis no modulo de contratos passa a ser feita pelo backend. O frontend coleta/mapeia os valores das variaveis e envia ao backend, que retorna o HTML ja substituido.

Autenticacao padrao via Authorization: Bearer {token} + x-company-id.

---

Endpoints

1. POST /api/v1/contracts/substitute-variables

Recebe templateId + valores de variaveis por grupo, substitui no HTML do template, retorna HTML substituido.

Request:

{
  "templateId": "uuid-do-template",
  "groups": [
    {
      "groupId": "uuid-do-grupo",
      "groupName": "Nome do Grupo",
      "variableValues": {
        "var-id-1": "Joao Silva",
        "var-id-2": "123.456.789-00",
        "var-id-3": "empresa@email.com"
      }
    }
  ]
}

Response 200:

{
  "data": [
    {
      "groupId": "uuid-do-grupo",
      "groupName": "Nome do Grupo",
      "htmlContent": "<p>Contratante: <span data-var=\"nome\" data-var-id=\"var-id-1\" class=\"variable-marker\" style=\"background:rgba(21,207,101,0.15);border:1px solid rgba(21,207,101,0.4);border-radius:2px;padding:0 2px\">Joao Silva</span></p>"
    }
  ]
}

Erros:

• 404 - Template nao encontrado
• 422 - Payload invalido (templateId ausente, groups vazio)

Logica de substituicao:

1. Buscar template pelo templateId, obter htmlContent
2. Para cada group no array:
   • Parsear o htmlContent como HTML
   • Encontrar todos elementos com atributo data-var-id
   • Para cada marker, buscar valor em variableValues[data-var-id]
   • Se encontrar valor, substituir o textContent do elemento pelo valor
   • Aplicar estilo inline: background:rgba(21,207,101,0.15);border:1px solid rgba(21,207,101,0.4);border-radius:2px;padding:0 2px
3. Retornar array com { groupId, groupName, htmlContent } para cada grupo

---

2. GET /api/v1/contracts/:id/review

O endpoint de review deve retornar htmlContent ja substituido em cada ReviewContractItem. O backend ja tem os variableValues salvos no contrato - deve usa-los para substituir antes de retornar.

Response esperada (campo contracts[].htmlContent): HTML com variaveis ja substituidas (nao mais os placeholders).

{
  "data": {
    "contracts": [
      {
        "id": "uuid",
        "groupId": "uuid-do-grupo",
        "groupName": "Nome do Grupo",
        "partName": "Joao Silva",
        "htmlContent": "<p>HTML com variaveis JA SUBSTITUIDAS</p>",
        "status": "pending",
        "commentsCount": 0,
        "approvals": [],
        "totalRequired": 2,
        "approvedCount": 0
      }
    ],
    "reviewers": [],
    "allApproved": false
  }
}

---

3. POST /api/v1/contracts/generate-pdfs

O endpoint de geracao de PDF ja recebe variableValues por grupo. Confirmar que o backend faz a substituicao no HTML antes de gerar o PDF. Mesma logica de substituicao do endpoint 1.

Request (ja existente):

{
  "templateId": "uuid-do-template",
  "groups": [
    {
      "groupId": "uuid-do-grupo",
      "groupName": "Nome do Grupo",
      "variableValues": {
        "var-id-1": "Joao Silva"
      }
    }
  ]
}

---

Mapeamento de Variaveis

O backend precisa ter registrado todas as variaveis que o frontend auto-resolve. O backend deve auto-resolver variaveis com source contract e provider usando os dados das partes do contrato.

Tabela de mapeamento

Padrao do nome da variavel	Fonte	Campo
nome_completo, nome, name	Person	name
email, e_mail	Person	email
cpf	Person (natural)	document (formatado XXX.XXX.XXX-XX)
cnpj	Person (legal)	cnpj (formatado XX.XXX.XXX/XXXX-XX)
razao_social, razaosocial	Person (legal)	legalName
telefone, phone, tel	Person	phone (formatado (XX) XXXXX-XXXX)
documento, document	Person	document

Fontes de variaveis (source)

Source	Descricao	Resolucao
contract	Dados do tomador/empresa contratante	Auto-resolver usando dados da empresa contratante
provider	Dados do prestador/parte do contrato	Auto-resolver usando dados do prestador vinculado ao grupo
manual_input	Valor inserido manualmente pelo usuario	Usar valor enviado no payload variableValues

Logica de auto-resolucao

1. Ao receber o payload, verificar cada variavel do template
2. Se a variavel tem source = contract ou source = provider, buscar o valor automaticamente nos dados da parte correspondente
3. Se o valor ja foi enviado em variableValues, o valor enviado tem prioridade
4. Variaveis com source = manual_input usam exclusivamente o valor do payload

---

Estilo inline para variaveis substituidas

Ao substituir uma variavel, aplicar o seguinte estilo inline no elemento <span>:

background: rgba(21, 207, 101, 0.15);
border: 1px solid rgba(21, 207, 101, 0.4);
border-radius: 2px;
padding: 0 2px;

---

Estrutura dos markers no HTML

Os markers de variaveis no HTML do template seguem este formato:

<span data-var="nome_variavel" data-var-id="uuid-da-variavel" class="variable-marker">
  placeholder ou valor
</span>

• data-var: nome legivel da variavel
• data-var-id: UUID unico da variavel (chave para buscar valor em variableValues)
• class="variable-marker": classe CSS do marker

---

Resumo de impacto

Endpoint	Acao necessaria
POST /contracts/substitute-variables	Novo - Criar endpoint
GET /contracts/:id/review	Alterar - Retornar HTML ja substituido
POST /contracts/generate-pdfs	Verificar - Confirmar que substitui antes de gerar PDF
Mapeamento de variaveis	Implementar - Auto-resolucao por source