Renderização

Geração de documentos HTML e PDF a partir de templates publicados.

Renderizar HTML

POST /api/v1/document-templates/:id/render

Renderiza o template usando a última versão publicada e as variáveis fornecidas.

Request

{
  "variables": {
    "clientName": "Maria Santos",
    "clientCpf": "987.654.321-00",
    "loanAmount": 15000,
    "installments": 24,
    "installmentValue": 750.00,
    "hasGuarantor": false
  },
  "businessId": "loan-12345",
  "metadata": {
    "source": "mobile-app",
    "version": "2.1.0"
  }
}

Campo	Tipo	Obrigatório	Descrição
variables	object	Sim	Variáveis para renderização
businessId	string	Não	ID de contexto de negócio (ex: ID do empréstimo)
metadata	object	Não	Metadados adicionais para auditoria

Response

{
  "data": {
    "type": "rendered-documents",
    "id": "rendered-doc-uuid",
    "attributes": {
      "html": "<h1>Contrato de Empréstimo</h1>\n<p>Eu, Maria Santos, CPF 987.654.321-00, declaro...</p>\n<p>Valor: R$ 15000</p>\n<p>Parcelas: 24x de R$ 750</p>",
      "templateId": "550e8400-e29b-41d4-a716-446655440000",
      "templateVersionNumber": 3
    }
  }
}

Renderizar PDF

POST /api/v1/document-templates/:id/render/pdf

Renderiza o template e converte para PDF. Retorna o PDF codificado em base64.

Requisitos

Requer o microserviço pdf-renderer configurado via PDF_RENDERER_URL.

Request

{
  "variables": {
    "clientName": "Maria Santos",
    "clientCpf": "987.654.321-00",
    "loanAmount": 15000,
    "installments": 24,
    "installmentValue": 750.00
  },
  "businessId": "loan-12345"
}

Response

{
  "data": {
    "type": "rendered-documents",
    "id": "rendered-doc-uuid",
    "attributes": {
      "templateId": "550e8400-e29b-41d4-a716-446655440000",
      "templateVersionNumber": 3,
      "outputFormat": "PDF",
      "pdfBase64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PAovVHlwZSAvUGFnZQovUGFyZW50..."
    }
  }
}

Decodificando o PDF

// JavaScript/Node.js
const pdfBuffer = Buffer.from(response.data.attributes.pdfBase64, 'base64');
fs.writeFileSync('contrato.pdf', pdfBuffer);

// Browser
const blob = new Blob(
  [Uint8Array.from(atob(pdfBase64), c => c.charCodeAt(0))],
  { type: 'application/pdf' }
);
const url = URL.createObjectURL(blob);
window.open(url);

# Python
import base64

pdf_bytes = base64.b64decode(response['data']['attributes']['pdfBase64'])
with open('contrato.pdf', 'wb') as f:
    f.write(pdf_bytes)

Preview

POST /api/v1/document-templates/:id/preview

Renderiza o template para visualização prévia. Diferente do render:

• Não cria registro de documento renderizado
• Não valida variáveis obrigatórias (permite preview parcial)
• Usa o conteúdo atual do template (não apenas versões publicadas)
• Ideal para desenvolvimento e testes

Request

{
  "variables": {
    "clientName": "João Teste"
  }
}

Se variables não for fornecido, usa o sampleData do template.

Response

{
  "data": {
    "type": "template-previews",
    "attributes": {
      "html": "<h1>Contrato de Empréstimo</h1>\n<p>Eu, João Teste, CPF , declaro...</p>"
    }
  }
}

Validação de Variáveis

A renderização valida todas as variáveis antes de processar o template:

Variáveis Obrigatórias

{
  "code": "VALIDATION",
  "message": "Required variable 'clientName' is missing",
  "statusCode": 400
}

Tipos Incorretos

{
  "code": "VALIDATION", 
  "message": "Variable 'loanAmount' must be a number",
  "statusCode": 400
}

Valores Default

Variáveis opcionais com default definido são preenchidas automaticamente:

// Definição
{ "name": "hasGuarantor", "type": "BOOLEAN", "required": false, "default": false }

// Input (sem hasGuarantor)
{ "clientName": "Maria" }

// Resultado: hasGuarantor = false

Histórico de Documentos

Cada renderização (exceto preview) cria um registro em RenderedDocument contendo:

Campo	Descrição
id	UUID do documento renderizado
templateId	ID do template usado
templateVersionNumber	Versão exata usada na renderização
inputData	Variáveis fornecidas (para reprodutibilidade)
outputFormat	HTML ou PDF
outputHtml	HTML gerado
businessId	Contexto de negócio (opcional)
metadata	Metadados adicionais
createdAt	Data/hora da renderização

Isso permite:

• Auditoria: Saber exatamente o que foi renderizado, quando e com quais dados
• Reprodutibilidade: Recriar o documento exato usando templateVersionNumber + inputData
• Compliance: Rastreabilidade para documentos legais

Códigos de Erro

Código	Mensagem	Descrição
404	Template not found	Template não existe ou não pertence à organização
404	Template version 'latest' not found	Template nunca foi publicado
400	Template must be published before rendering	Template ainda é rascunho
400	Required variable 'X' is missing	Variável obrigatória não fornecida
400	Variable 'X' must be a Y	Tipo de variável incorreto
400	PDF rendering is not configured	PDF_RENDERER_URL não definida
500	PDF renderer service is unavailable	Sidecar não está rodando

Exemplos de Uso

Gerar Contrato para Assinatura

// 1. Renderizar PDF
const response = await api.post(`/document-templates/${templateId}/render/pdf`, {
  variables: {
    clientName: customer.name,
    clientCpf: customer.cpf,
    loanAmount: loan.amount,
    installments: loan.installments,
    installmentValue: loan.installmentValue,
  },
  businessId: loan.id,
});

// 2. Usar com E-Signature
const signatureRequest = await api.post('/e-signature/signature-requests', {
  documentBase64: response.data.attributes.pdfBase64,
  signers: [{ email: customer.email, name: customer.name }],
});

Preview em Tempo Real (Editor)

// Debounce para não sobrecarregar a API
const debouncedPreview = debounce(async (variables) => {
  const response = await api.post(`/document-templates/${templateId}/preview`, {
    variables,
  });
  setPreviewHtml(response.data.attributes.html);
}, 500);

// Atualizar preview conforme usuário edita variáveis
useEffect(() => {
  debouncedPreview(formValues);
}, [formValues]);