# Renderização de PDF

> capabilities.pdf.render transforma HTML em PDF sem conhecer endpoint, credencial ou implementação — com limites, cancelamento e erros com retryable.

## 1. Declare a dependência

Em `oon.deploy.json` (não em `central.app.json`):

```json title="oon.deploy.json"
{
  "capabilities": {
    "pdfRendering": { "required": true, "minVersion": "1.0.0" }
  }
}
```

Não adicione URL, usuário, senha ou implementation reference — o runtime resolve na publicação.

## 2. Crie a rota

```javascript title="backend/src/routes/pdf.js"
const { capabilities, defineRoutes, GenericError } = require("@oondemand/oon-core-back");

defineRoutes("/pdf", (router) => {
  router.private.post("/render", { permission: "pdf.render" }, async (req, res) => {
    if (typeof req.body?.html !== "string" || !req.body.html.trim()) {
      throw new GenericError("Informe o HTML.", { statusCode: 422, code: "PDF_HTML_REQUIRED" });
    }

    const controller = new AbortController();
    const abort = () => controller.abort();
    req.once("aborted", abort);
    res.once("close", abort);

    try {
      const pdf = await capabilities.pdf.render(
        { html: req.body.html, format: req.body.format || "A4", printBackground: true },
        {
          ...req.accessContext,
          correlationId: req.correlationId,
          environment: process.env.APP_ENVIRONMENT,
          signal: controller.signal,
        },
      );
      res.type("application/pdf");
      res.set("Content-Disposition", 'attachment; filename="documento.pdf"');
      res.send(pdf);
    } finally {
      req.off("aborted", abort);
      res.off("close", abort);
    }
  });
});
```

Declare `pdf.render` em `rbac.permissions` e conceda só aos perfis necessários.

## Assinatura

```ts
capabilities.pdf.render(input, context): Promise<Buffer>
```

| `input` | Tipo | Regra / padrão |
|---|---|---|
| `html` | string | obrigatório; máximo padrão de 2 MiB |
| `format` | `A3 \| A4 \| A5 \| Letter \| Legal` | `A4` |
| `landscape` | boolean | `false` |
| `marginTop/Bottom/Left/Right` | number | polegadas, 0 a 4; `0.39` |
| `printBackground` | boolean | `true` |
| `timeoutMs` | number | mín. 1.000; padrão 30.000; máx. do runtime 60.000 |

`context` aceita `tenantId`, `appCode`, `environment`, `operationId`, `correlationId`/`requestId`, `signal` e, só em testes, `fetchImpl`. A saída começa com `%PDF-` e tem limite padrão de 20 MiB. O alias `capabilities.pdfRendering.render` é compatível.

## 3. Preview e download no frontend

```tsx
<iframe title="Prévia" sandbox="" srcDoc={html} />
```

```tsx
import { useOonApi } from "@oondemand/oon-core-front";

function DownloadPdfButton({ html }: { html: string }) {
  const { http } = useOonApi();
  async function download() {
    const response = await http.post("/pdf/render", { html, format: "A4" }, { responseType: "blob" });
    const url = URL.createObjectURL(response.data);
    const link = document.createElement("a");
    link.href = url;
    link.download = "documento.pdf";
    link.click();
    URL.revokeObjectURL(url);
  }
  return <button onClick={download}>Gerar PDF</button>;
}
```

Nunca envie a geração diretamente a um endpoint de infraestrutura pelo navegador.

## Erros

`PdfRenderingError` expõe `code`, `statusCode`, `retryable` e detalhes sanitizados.

| Código | Retry | Significado |
|---|:---:|---|
| `PDF_RENDERING_INVALID_INPUT` | não | HTML vazio ou acima do limite |
| `PDF_RENDERING_INVALID_OPTIONS` | não | formato, margem ou opção inválida |
| `PDF_RENDERING_UNAVAILABLE` | sim | capability não resolvida no ambiente |
| `PDF_RENDERING_CREDENTIAL_UNAVAILABLE` | sim | credencial interna não injetada |
| `PDF_RENDERING_IMPLEMENTATION_ERROR` | sim | implementação respondeu com falha |
| `PDF_RENDERING_TIMEOUT` | sim | prazo excedido ou sinal abortado |
| `PDF_RENDERING_SATURATED` | sim | concorrência/fila excedida |
| `PDF_RENDERING_TRANSPORT_ERROR` | sim | falha transitória de transporte |
| `PDF_RENDERING_INVALID_OUTPUT` | sim | saída inválida ou acima do limite |

Repita apenas quando `error.retryable === true`, com backoff e idempotência na operação chamadora.

## Segurança

- trate HTML do usuário como não confiável; sanitize e use interpolação escapada;
- prefira HTML autocontido — recursos remotos tornam o resultado não determinístico;
- nunca inclua segredos no HTML;
- não registre HTML nem bytes do PDF; registre correlação, duração, tamanhos e código;
- propague cancelamento por `AbortSignal`;
- no runtime local, falha fechado com `PDF_RENDERING_UNAVAILABLE`;
- em testes, injete um transport fake por `capabilities.configurePdfRendering` que devolva bytes iniciados por `%PDF-`.

Fonte: https://sdk.oonapps.com/docs/capabilities/pdf