Modos de Operação

Entenda a diferença entre CONVERT e RENDER e quando usar cada modo

Modos de Operação

O RenderHub oferece dois modos distintos de geração de PDFs, cada um otimizado para diferentes casos de uso.

Visão Geral

Modo	Uso	Entrada	Melhor Para
CONVERT	Conversão direta	HTML, DOCX, Markdown, XML, CSV, JSON	Documentos prontos, conversões simples
RENDER	Template + dados	Template ID + JSON data	Documentos dinâmicos, faturas, relatórios

Modo CONVERT

Conversão direta de conteúdo em PDF sem usar templates.

Quando Usar

✅ Use CONVERT quando:

Você já tem o conteúdo completo pronto (HTML, DOCX, etc.)
Não precisa reutilizar a estrutura do documento
Quer conversão rápida one-off
Está migrando documentos existentes

❌ Não use CONVERT quando:

Precisa gerar múltiplos documentos com mesma estrutura
Dados mudam frequentemente
Quer separar design de dados

Exemplo: Converter HTML

const response = await axios.post('https://renderhub.com/api/v1/render', {
  mode: 'CONVERT',
  input_type: 'html',
  data: `
    <html>
      <head>
        <style>
          body { font-family: Arial, sans-serif; }
          h1 { color: #333; }
        </style>
      </head>
      <body>
        <h1>Relatório de Vendas</h1>
        <p>Total: R$ 10.500,00</p>
      </body>
    </html>
  `
}, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

// response.data.pdf_base64 → PDF pronto

Exemplo: Converter DOCX

const fs = require('fs');

// Ler arquivo DOCX existente
const docxBuffer = fs.readFileSync('relatorio.docx');
const docxBase64 = docxBuffer.toString('base64');

const response = await axios.post('https://renderhub.com/api/v1/render', {
  mode: 'CONVERT',
  input_type: 'docx',
  data: docxBase64
}, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

Exemplo: Converter Markdown

const markdown = `
# Documentação do Projeto

## Instalação

\`\`\`bash
npm install meu-pacote
\`\`\`

## Uso

Exemplo de código...
`;

const response = await axios.post('https://renderhub.com/api/v1/render', {
  mode: 'CONVERT',
  input_type: 'markdown',
  data: markdown
}, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

Modo RENDER

Renderização baseada em templates com dados dinâmicos.

Quando Usar

✅ Use RENDER quando:

Precisa gerar múltiplos documentos com mesma estrutura
Quer separar design (template) de dados (JSON)
Dados vêm de banco de dados ou API
Precisa de versionamento de templates
Quer reutilizar templates entre projetos

❌ Não use RENDER quando:

Precisa converter um documento único
Não tem estrutura repetitiva
O conteúdo muda completamente a cada vez

Como Funciona

Crie um template no Dashboard ou via API
Armazene o template (recebe um template_id)
Renderize passando dados JSON para preencher o template

Exemplo: Template de Fatura

Passo 1: Criar Template (via Dashboard ou API)

<!-- Template ID: tpl_invoice_001 -->
<html>
  <head>
    <style>
      body { font-family: Arial; padding: 40px; }
      .header { border-bottom: 2px solid #333; padding-bottom: 20px; }
      .invoice-number { color: #666; }
      .total { font-size: 24px; font-weight: bold; color: #000; }
    </style>
  </head>
  <body>
    <div class="header">
      <h1>{{company_name}}</h1>
      <p class="invoice-number">Fatura #{{invoice_number}}</p>
    </div>

    <h2>Cliente</h2>
    <p>{{customer_name}}<br>{{customer_email}}</p>

    <h2>Itens</h2>
    <table>
      {{#each items}}
      <tr>
        <td>{{this.description}}</td>
        <td>{{this.quantity}}x</td>
        <td>R$ {{this.price}}</td>
      </tr>
      {{/each}}
    </table>

    <p class="total">Total: R$ {{total}}</p>
  </body>
</html>

Passo 2: Renderizar com Dados

const response = await axios.post('https://renderhub.com/api/v1/render', {
  mode: 'RENDER',
  template_id: 'tpl_invoice_001',
  data: {
    company_name: 'Minha Empresa LTDA',
    invoice_number: '2024-001',
    customer_name: 'João Silva',
    customer_email: 'joao@email.com',
    items: [
      { description: 'Consultoria', quantity: 10, price: '150,00' },
      { description: 'Desenvolvimento', quantity: 20, price: '200,00' }
    ],
    total: '5.500,00'
  }
}, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

Resultado: PDF de fatura preenchido com os dados específicos do cliente.

Vantagens do Modo RENDER

1. Reutilização

// Gerar 100 faturas com mesmo template
for (const customer of customers) {
  await generateInvoice({
    mode: 'RENDER',
    template_id: 'tpl_invoice_001',
    data: customer
  });
}

2. Versionamento

// Versão antiga (mantida para histórico)
template_id: 'tpl_invoice_v1'

// Versão nova (com novos campos)
template_id: 'tpl_invoice_v2'

3. Separação de Responsabilidades

Designer: Cria templates no Dashboard
Desenvolvedor: Envia dados via API
Mudanças: Atualizar template não requer deploy de código

Comparação Prática

Cenário 1: Converter Documento Único

// ✅ CONVERT - Melhor escolha
{
  mode: 'CONVERT',
  input_type: 'html',
  data: '<html>...</html>'
}

Cenário 2: Gerar 1000 Faturas

// ❌ CONVERT - Péssima escolha (código duplicado)
{
  mode: 'CONVERT',
  input_type: 'html',
  data: `<html>...${customer.name}...${customer.total}...</html>`
}

// ✅ RENDER - Melhor escolha (template reutilizável)
{
  mode: 'RENDER',
  template_id: 'tpl_invoice',
  data: { name: customer.name, total: customer.total }
}

Cenário 3: Documentação Markdown → PDF

// ✅ CONVERT - Melhor escolha
{
  mode: 'CONVERT',
  input_type: 'markdown',
  data: markdownContent
}

Cenário 4: Certificados Personalizados

// ✅ RENDER - Melhor escolha (mesmo design, dados diferentes)
{
  mode: 'RENDER',
  template_id: 'tpl_certificate',
  data: { student_name: 'Maria', course: 'Python Avançado', date: '2024-01-15' }
}

Opções Comuns

Ambos os modos suportam as mesmas opções de configuração:

{
  mode: 'CONVERT', // ou 'RENDER'

  // Opções de página
  page_size: 'A4',        // A4, Letter, Legal
  orientation: 'portrait', // portrait, landscape

  // Margens (em mm)
  margin_top: 20,
  margin_bottom: 20,
  margin_left: 15,
  margin_right: 15,

  // Cabeçalho/Rodapé
  header_html: '<p>Confidencial</p>',
  footer_html: '<p>Página {{page}} de {{total}}</p>',

  // Outras opções
  print_background: true,
  scale: 1.0
}

Melhores Práticas

Para CONVERT

Use quando o conteúdo é único ou muda completamente
Ideal para conversões batch de arquivos existentes
Bom para protótipos e testes rápidos

Para RENDER

Use quando há estrutura repetitiva
Armazene templates no RenderHub (não no seu código)
Versione templates conforme evoluem
Use dados tipados para evitar erros

Performance

Métrica	CONVERT	RENDER
Primeira geração	~400ms	~450ms (cache de template)
Gerações subsequentes	~400ms	~350ms (template em cache)
Escalabilidade	Linear	Melhor com cache

Próximos Passos

Tipos de Entrada - Formatos suportados (HTML, DOCX, Markdown, etc.)
Templates - Guia completo de criação de templates
Referência da API - Documentação completa da API

Modos de Operação

Modos de Operação

Visão Geral

Modo CONVERT

Quando Usar

Exemplo: Converter HTML

Exemplo: Converter DOCX

Exemplo: Converter Markdown

Modo RENDER

Quando Usar

Como Funciona

Exemplo: Template de Fatura

Vantagens do Modo RENDER

Comparação Prática

Cenário 1: Converter Documento Único

Cenário 2: Gerar 1000 Faturas

Cenário 3: Documentação Markdown → PDF

Cenário 4: Certificados Personalizados

Opções Comuns

Melhores Práticas

Para CONVERT

Para RENDER

Performance

Próximos Passos

On this page