> ## Documentation Index
> Fetch the complete documentation index at: https://developers.insuranceboosters.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generar PDF de un registro

> Renderiza una plantilla pdf_template existente contra un registro del tablero.

Genera un archivo PDF con una plantilla creada previamente desde la plataforma.

Si es tu primera integración, sigue primero la [guía completa](/tableros/generar-pdf). Para llamar este endpoint necesitas:

* Una [API key](/autenticacion).
* El ID del tablero (`databaseId`).
* El ID del registro (`recordId`).
* `fieldId` y `templateId`, obtenidos con [Listar plantillas PDF](/tableros/listar-plantillas-pdf).

## Endpoint

```text theme={null}
POST /databases/{databaseId}/records/{recordId}/pdf-template
```

## Parámetros de ruta

| Parámetro    | Descripción                                                |
| ------------ | ---------------------------------------------------------- |
| `databaseId` | ID del tablero.                                            |
| `recordId`   | ID del registro cuyos valores se insertan en la plantilla. |

## Body

| Campo        | Tipo     | Requerido | Descripción                                                                             |
| ------------ | -------- | --------- | --------------------------------------------------------------------------------------- |
| `fieldId`    | `string` | Sí        | `id` del campo con `"type": "pdf_template"`.                                            |
| `templateId` | `string` | Sí        | `id` de un elemento en `pdfTemplateConfig.templates`.                                   |
| `values`     | `object` | No        | Claves que sustituyen o complementan los valores del registro únicamente para este PDF. |

Consulta [Listar plantillas PDF](/tableros/listar-plantillas-pdf) para conocer los IDs y `runtimeFields` que acepta la plantilla. También puedes enviar la `key` de un campo compatible del tablero para sustituir su valor.

<Note>
  No envíes el diseño de la plantilla. La API usa la versión guardada en la plataforma.
</Note>

## Ejemplo: descargar el PDF

```bash theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/databases/{databaseId}/records/{recordId}/pdf-template" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "fieldId": "<field-id>",
    "templateId": "<template-id>",
    "values": {
      "observaciones": "Texto capturado al generar"
    }
  }' \
  --output documento.pdf
```

Sustituye `{databaseId}`, `{recordId}`, `<field-id>` y `<template-id>` por los valores de tu tablero.

Si la plantilla no tiene `runtimeFields`, puedes omitir `values`:

```json theme={null}
{
  "fieldId": "<field-id>",
  "templateId": "<template-id>"
}
```

## Respuesta exitosa (`200`)

El body es el archivo PDF. Encabezados relevantes:

| Encabezado            | Valor                                 |
| --------------------- | ------------------------------------- |
| `Content-Type`        | `application/pdf`                     |
| `Content-Disposition` | `attachment; filename="<nombre>.pdf"` |
| `Cache-Control`       | `no-store`                            |

Los valores enviados no se guardan en el registro. Si una clave también existe en el tablero, el valor del body tiene precedencia solamente durante esta generación.

## Recibir el archivo con JavaScript

La respuesta no contiene JSON. Lee el body como bytes:

```js theme={null}
import { writeFile } from "node:fs/promises";

const apiUrl =
  process.env.IB_API_URL ?? "https://api.insuranceboosters.com/api/v1";
const apiKey = process.env.IB_API_KEY;
const databaseId = "<database-id>";
const recordId = "<record-id>";
const fieldId = "<field-id>";
const templateId = "<template-id>";

if (!apiKey) {
  throw new Error("Falta la variable IB_API_KEY");
}

const response = await fetch(
  `${apiUrl}/databases/${databaseId}/records/${recordId}/pdf-template`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-ib-api-key": apiKey,
    },
    body: JSON.stringify({
      fieldId,
      templateId,
      values: {
        observaciones: "Texto capturado al generar",
      },
    }),
  }
);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const pdf = Buffer.from(await response.arrayBuffer());
await writeFile("documento.pdf", pdf);
```

Sustituye los cuatro IDs. Guarda la API key en `IB_API_KEY`; no la incluyas directamente en el código fuente.

## Límites

* Máximo 50 propiedades dentro de `values`.
* Máximo 10,000 caracteres por string.
* Valores permitidos: string, número, booleano o `null`.
* Máximo 30 generaciones por minuto por API key.
* La renderización puede tardar hasta 58 segundos.

El límite de 30 se comparte entre todos los tableros y plantillas usados por la misma API key. Al superarlo, la API responde `429`.

## Errores frecuentes

| HTTP  | Qué significa                                                         | Qué hacer                                                                      |
| ----- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `400` | Faltan IDs o `values` contiene una clave, tipo o tamaño no permitido. | Consulta el catálogo y corrige los valores enviados.                           |
| `401` | API key inválida o faltante.                                          | Verifica `x-ib-api-key`.                                                       |
| `403` | Tu integración no puede acceder al registro.                          | Confirma el acceso al tablero y al registro.                                   |
| `404` | El tablero, registro, campo o plantilla no existe.                    | Confirma los IDs con [Listar plantillas PDF](/tableros/listar-plantillas-pdf). |
| `422` | La plantilla no se pudo renderizar.                                   | Revisa el mensaje y corrige la plantilla en el tablero.                        |
| `429` | La API key superó 30 generaciones por minuto.                         | Espera los segundos indicados en `Retry-After`.                                |
| `500` | No fue posible generar el PDF.                                        | Reintenta; si continúa, contacta soporte.                                      |

Los errores incluyen un código estable:

```json theme={null}
{
  "code": "PDF_RUNTIME_VALUES_INVALID",
  "message": "values contains a key not used by this template: \"comentaro\""
}
```

Antes de leer el body como PDF, comprueba siempre `response.ok` o el código HTTP. Las respuestas de error son JSON.


## OpenAPI

````yaml openapi/tableros-v1.yaml POST /databases/{databaseId}/records/{recordId}/pdf-template
openapi: 3.1.0
info:
  title: Insurance Boosters API — Tableros
  version: 1.0.0
  description: API pública para administrar tableros, campos, registros, archivos y PDF.
  license:
    name: Propietaria
    url: https://insuranceboosters.com
servers:
  - url: https://api.insuranceboosters.com/api/v1
    description: Producción
security:
  - IbApiKey: []
tags:
  - name: Tableros
    description: Administración de tableros.
  - name: Campos
    description: Configuración del esquema de un tablero.
  - name: Registros
    description: Lectura y escritura de registros.
  - name: Archivos
    description: Archivos adjuntos a registros.
  - name: PDF
    description: Generación de PDF a partir de plantillas del tablero.
paths:
  /databases/{databaseId}/records/{recordId}/pdf-template:
    parameters:
      - $ref: '#/components/parameters/DatabaseId'
      - $ref: '#/components/parameters/RecordId'
    post:
      tags:
        - PDF
      summary: Generar PDF de un registro
      description: |
        Genera un archivo PDF con una plantilla creada desde la plataforma.
        Los datos del registro se cargan automáticamente. Envía en `values` los
        elementos de `runtimeFields` y, si lo necesitas, valores que deban
        sustituir temporalmente una columna del registro.
      operationId: generateDatabaseRecordPdf
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePdfTemplateRequest'
            example:
              fieldId: <field-id>
              templateId: <template-id>
              values:
                observaciones: Texto capturado al generar
      responses:
        '200':
          description: Documento PDF generado.
          headers:
            Content-Disposition:
              description: Nombre de archivo configurado por la plantilla.
              schema:
                type: string
                example: attachment; filename="poliza-POL-1001.pdf"
            Cache-Control:
              description: El documento no debe almacenarse en caché.
              schema:
                type: string
                example: no-store
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    DatabaseId:
      name: databaseId
      in: path
      required: true
      description: ID del tablero.
      schema:
        type: string
    RecordId:
      name: recordId
      in: path
      required: true
      description: ID del registro.
      schema:
        type: string
  schemas:
    GeneratePdfTemplateRequest:
      type: object
      additionalProperties: false
      required:
        - fieldId
        - templateId
      properties:
        fieldId:
          type: string
          minLength: 1
          description: >-
            Valor `fieldId` devuelto por `GET
            /databases/{databaseId}/pdf-templates`.
        templateId:
          type: string
          minLength: 1
          description: >-
            Valor `templateId` devuelto por `GET
            /databases/{databaseId}/pdf-templates`.
        values:
          type: object
          maxProperties: 50
          additionalProperties:
            oneOf:
              - type: string
                maxLength: 10000
              - type: number
              - type: boolean
              - type: 'null'
          description: |
            Valores opcionales indexados por `key`. Incluye aquí los
            `runtimeFields` de la plantilla. Si envías la `key` de una columna
            del tablero, sustituye su valor únicamente para este PDF.
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        error:
          type: string
      additionalProperties: false
  responses:
    BadRequest:
      description: Solicitud inválida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: API key inválida o faltante.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: La integración no tiene acceso al recurso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Recurso no encontrado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: La plantilla no se pudo renderizar.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Se excedió el límite de generación de PDF.
      headers:
        Retry-After:
          description: Segundos antes de reintentar.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Error del servicio.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    IbApiKey:
      type: apiKey
      in: header
      name: x-ib-api-key
      description: API key de Insurance Boosters.

````