POST /render

Referência completa da API de renderização de PDFs

POST /api/v1/render

Endpoint principal para gerar PDFs a partir de diferentes formatos de entrada.

URL Base

https://renderhub.com/api/v1/render

Autenticação

Todas as requisições devem incluir sua chave de API no cabeçalho Authorization:

Authorization: Bearer SUA_CHAVE_API

Request

Headers

Header	Valor	Obrigatório
`Authorization`	`Bearer {api_key}`	✅ Sim
`Content-Type`	`application/json`	✅ Sim

Body Parameters

Parâmetros Principais

Parâmetro	Tipo	Obrigatório	Descrição
`mode`	string	✅ Sim	Modo de operação: `CONVERT` ou `RENDER`
`input_type`	string	Condicional*	Formato de entrada: `html`, `docx`, `markdown`, `xml`, `csv`, `json`
`data`	string	Condicional*	Conteúdo a ser convertido (texto ou base64)
`template_id`	string	Condicional**	ID do template (apenas modo `RENDER`)

* Obrigatório quando mode: "CONVERT" ** Obrigatório quando mode: "RENDER"

Opções de Página

Parâmetro	Tipo	Padrão	Descrição
`page_size`	string	`A4`	Tamanho: `A4`, `A3`, `Letter`, `Legal`, `Tabloid`
`orientation`	string	`portrait`	Orientação: `portrait`, `landscape`
`margin_top`	number	`20`	Margem superior em mm (0-100)
`margin_bottom`	number	`20`	Margem inferior em mm (0-100)
`margin_left`	number	`15`	Margem esquerda em mm (0-100)
`margin_right`	number	`15`	Margem direita em mm (0-100)

Cabeçalho e Rodapé

Parâmetro	Tipo	Padrão	Descrição
`header_html`	string	`null`	HTML do cabeçalho (suporta `{{page}}`, `{{total}}`, `{{date}}`)
`footer_html`	string	`null`	HTML do rodapé (suporta `{{page}}`, `{{total}}`, `{{date}}`)
`header_height`	number	`10`	Altura do cabeçalho em mm
`footer_height`	number	`10`	Altura do rodapé em mm

Opções Avançadas

Parâmetro	Tipo	Padrão	Descrição
`print_background`	boolean	`true`	Imprimir cores e imagens de fundo
`scale`	number	`1.0`	Escala da página (0.1 - 2.0)
`wait_for`	string	`load`	Aguardar: `load`, `domcontentloaded`, `networkidle`
`wait_time`	number	`0`	Tempo adicional de espera em ms (0-5000)
`emulate_media`	string	`print`	Tipo de mídia CSS: `screen`, `print`

Webhook (Assíncrono)

Parâmetro	Tipo	Descrição
`webhook_url`	string	URL para receber callback quando PDF estiver pronto
`webhook_method`	string	Método HTTP: `POST` (padrão), `PUT`

Exemplo: Modo CONVERT

curl -X POST https://renderhub.com/api/v1/render \
  -H "Authorization: Bearer rh_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "CONVERT",
    "input_type": "html",
    "data": "<html><body><h1>Meu PDF</h1></body></html>",
    "page_size": "A4",
    "orientation": "portrait",
    "margin_top": 20,
    "margin_bottom": 20,
    "margin_left": 15,
    "margin_right": 15,
    "print_background": true
  }'

Exemplo: Modo RENDER

curl -X POST https://renderhub.com/api/v1/render \
  -H "Authorization: Bearer rh_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "RENDER",
    "template_id": "tpl_invoice_001",
    "data": {
      "customer_name": "João Silva",
      "invoice_number": "2024-001",
      "total": "R$ 5.500,00"
    }
  }'

Exemplo: Com Cabeçalho/Rodapé

curl -X POST https://renderhub.com/api/v1/render \
  -H "Authorization: Bearer rh_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "CONVERT",
    "input_type": "html",
    "data": "<h1>Relatório</h1><p>Conteúdo...</p>",
    "header_html": "<div style=\"text-align: center; font-size: 10px;\">CONFIDENCIAL</div>",
    "footer_html": "<div style=\"text-align: center; font-size: 10px;\">Página {{page}} de {{total}} - {{date}}</div>",
    "header_height": 15,
    "footer_height": 15
  }'

Exemplo: Webhook Assíncrono

curl -X POST https://renderhub.com/api/v1/render \
  -H "Authorization: Bearer rh_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "CONVERT",
    "input_type": "html",
    "data": "<h1>PDF Grande</h1>",
    "webhook_url": "https://meuapp.com/webhook/pdf-ready"
  }'

Response

Success (200 OK)

Resposta Síncrona

{
  "id": "render_7kj3h2g1k4j5h6",
  "status": "DONE",
  "pdf_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...",
  "pages": 3,
  "file_size_kb": 245,
  "duration_ms": 1250,
  "created_at": "2024-01-15T10:30:00Z"
}

Resposta Assíncrona (com webhook)

{
  "id": "render_7kj3h2g1k4j5h6",
  "status": "QUEUED",
  "job_id": "job_abc123xyz",
  "webhook_url": "https://meuapp.com/webhook/pdf-ready",
  "estimated_time_ms": 3000,
  "created_at": "2024-01-15T10:30:00Z"
}

Response Fields

Campo	Tipo	Descrição
`id`	string	ID único da renderização
`status`	string	Status: `QUEUED`, `PROCESSING`, `DONE`, `FAILED`
`pdf_base64`	string	PDF codificado em base64 (apenas quando `DONE`)
`pages`	number	Número de páginas do PDF
`file_size_kb`	number	Tamanho do arquivo em KB
`duration_ms`	number	Tempo de processamento em milissegundos
`created_at`	string	Timestamp ISO 8601 da criação
`job_id`	string	ID do job (apenas modo assíncrono)
`webhook_url`	string	URL do webhook (apenas modo assíncrono)
`estimated_time_ms`	number	Tempo estimado (apenas modo assíncrono)

Callback do Webhook

Quando o PDF estiver pronto, o RenderHub envia um POST para sua webhook_url:

{
  "id": "render_7kj3h2g1k4j5h6",
  "status": "DONE",
  "job_id": "job_abc123xyz",
  "pdf_url": "https://renderhub.com/api/v1/download/render_7kj3h2g1k4j5h6",
  "pdf_expires_at": "2024-01-15T11:30:00Z",
  "pages": 3,
  "file_size_kb": 245,
  "duration_ms": 2800
}

Baixe o PDF da pdf_url dentro de 1 hora (expira automaticamente).

Errors

400 - Bad Request

Requisição inválida ou parâmetros incorretos.

{
  "error": "invalid_request",
  "message": "O campo 'mode' é obrigatório",
  "field": "mode",
  "code": 400
}

401 - Unauthorized

Chave de API ausente ou inválida.

{
  "error": "unauthorized",
  "message": "Chave de API inválida ou ausente",
  "code": 401
}

403 - Quota Exceeded

Quota mensal excedida.

{
  "error": "quota_exceeded",
  "message": "Quota mensal de 1.000 requisições excedida",
  "quota_reset": "2024-02-01T00:00:00Z",
  "code": 403
}

413 - Payload Too Large

Conteúdo excede o tamanho máximo permitido.

{
  "error": "payload_too_large",
  "message": "O tamanho do conteúdo excede 10 MB",
  "max_size_mb": 10,
  "received_size_mb": 15.2,
  "code": 413
}

422 - Unprocessable Entity

Erro ao processar o conteúdo.

{
  "error": "conversion_failed",
  "message": "Falha ao converter HTML: CSS inválido na linha 15",
  "details": "Unexpected token '}' at line 15",
  "code": 422
}

429 - Too Many Requests

Rate limit excedido.

{
  "error": "rate_limit_exceeded",
  "message": "Você excedeu 20 requisições por minuto",
  "retry_after": 45,
  "code": 429
}

500 - Internal Server Error

Erro interno do servidor.

{
  "error": "internal_error",
  "message": "Erro interno ao processar requisição",
  "request_id": "req_abc123",
  "code": 500
}

Rate Limits

Cada resposta inclui headers de rate limiting:

HTTP/1.1 200 OK
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1640995200
X-Quota-Limit: 1000
X-Quota-Remaining: 750
X-Quota-Reset: 1643673600

Exemplos por Linguagem

Node.js

const axios = require('axios');
const fs = require('fs');

async function generatePDF() {
  try {
    const response = await axios.post('https://renderhub.com/api/v1/render', {
      mode: 'CONVERT',
      input_type: 'html',
      data: '<html><body><h1>Olá RenderHub!</h1></body></html>',
      page_size: 'A4',
      orientation: 'portrait'
    }, {
      headers: {
        'Authorization': `Bearer ${process.env.RENDERHUB_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });

    // Salvar PDF
    const pdfBuffer = Buffer.from(response.data.pdf_base64, 'base64');
    fs.writeFileSync('output.pdf', pdfBuffer);

    console.log('✅ PDF gerado com sucesso!');
    console.log(`Páginas: ${response.data.pages}`);
    console.log(`Tamanho: ${response.data.file_size_kb} KB`);
  } catch (error) {
    if (error.response) {
      console.error('Erro:', error.response.data);
    } else {
      console.error('Erro:', error.message);
    }
  }
}

generatePDF();

Python

import os
import base64
import requests

API_KEY = os.getenv('RENDERHUB_API_KEY')

def generate_pdf():
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }

    data = {
        'mode': 'CONVERT',
        'input_type': 'html',
        'data': '<html><body><h1>Olá RenderHub!</h1></body></html>',
        'page_size': 'A4',
        'orientation': 'portrait'
    }

    response = requests.post(
        'https://renderhub.com/api/v1/render',
        headers=headers,
        json=data
    )

    if response.status_code == 200:
        result = response.json()

        # Decodificar e salvar PDF
        pdf_bytes = base64.b64decode(result['pdf_base64'])
        with open('output.pdf', 'wb') as f:
            f.write(pdf_bytes)

        print(f'✅ PDF gerado com sucesso!')
        print(f'Páginas: {result["pages"]}')
        print(f'Tamanho: {result["file_size_kb"]} KB')
    else:
        print(f'Erro: {response.json()}')

generate_pdf()

PHP

<?php

$apiKey = getenv('RENDERHUB_API_KEY');

$data = [
    'mode' => 'CONVERT',
    'input_type' => 'html',
    'data' => '<html><body><h1>Olá RenderHub!</h1></body></html>',
    'page_size' => 'A4',
    'orientation' => 'portrait'
];

$ch = curl_init('https://renderhub.com/api/v1/render');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);

    // Decodificar e salvar PDF
    $pdfBytes = base64_decode($result['pdf_base64']);
    file_put_contents('output.pdf', $pdfBytes);

    echo "✅ PDF gerado com sucesso!\n";
    echo "Páginas: {$result['pages']}\n";
    echo "Tamanho: {$result['file_size_kb']} KB\n";
} else {
    echo "Erro: $response\n";
}

Limites e Restrições

Recurso	Limite	Upgrade
Tamanho do payload	10 MB	Enterprise: 50 MB
Timeout	30 segundos	Enterprise: 60 segundos
Páginas por PDF	100 páginas	Enterprise: Ilimitado
Imagens externas	50 por documento	Enterprise: Ilimitado
JavaScript timeout	5 segundos	Enterprise: 10 segundos

Melhores Práticas

1. Sempre use HTTPS

// ✅ Correto
const url = 'https://www.renderhub.app/api/v1/render';

// ❌ Incorreto
const url = 'http://www.renderhub.app/api/v1/render';

2. Armazene a chave em variáveis de ambiente

// ✅ Correto
const apiKey = process.env.RENDERHUB_API_KEY;

// ❌ Incorreto
const apiKey = 'rh_live_abc123...';

3. Implemente retry com backoff

async function generatePDFWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await axios.post('/api/v1/render', data);
    } catch (error) {
      if (error.response?.status === 429) {
        const delay = error.response.headers['retry-after'] || (2 ** i);
        await sleep(delay * 1000);
      } else {
        throw error;
      }
    }
  }
}

4. Use webhooks para PDFs grandes

// Para PDFs que levam >5s
const response = await axios.post('/api/v1/render', {
  mode: 'CONVERT',
  input_type: 'html',
  data: largeHtmlContent,
  webhook_url: 'https://meuapp.com/webhook'
});
// Não espera o PDF, processa quando receber callback

5. Valide a entrada antes de enviar

// Valide HTML antes de enviar
const isValidHTML = html.includes('<html>') && html.includes('</html>');
if (!isValidHTML) {
  throw new Error('HTML inválido');
}

Próximos Passos

Códigos de Erro - Referência completa de erros
Webhooks - Guia de processamento assíncrono
Templates - API de gerenciamento de templates
Exemplos - Exemplos completos por linguagem