---
name: pdf_add_header_footer
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def pdf_add_header_footer(doc, header_text, footer_text, page_numbers) -> PDFDoc"
description: "Configura header y/o footer recurrente para todas las paginas del documento. Debe llamarse antes de pdf_add_page. El footer acepta {n} y {total} como placeholders para numeracion automatica."
tags: [pdf, header, footer, pagination, builder, infra, pendiente-usar]
uses_functions: []
uses_types: [pdf_doc_py_infra]
returns: [pdf_doc_py_infra]
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: doc
    desc: "PDFDoc inicializado con pdf_create, sin paginas aun (llamar antes de pdf_add_page)"
  - name: header_text
    desc: "texto centrado en el header de cada pagina; vacio deshabilita el header"
  - name: footer_text
    desc: "texto del footer; soporta {n} = numero de pagina y {total} = total de paginas"
  - name: page_numbers
    desc: "si True activa numeracion automatica; si footer_text esta vacio usa 'Pagina {n} de {total}'"
output: "PDFDoc con la configuracion de header/footer guardada; se aplica en cada pdf_add_page posterior"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/pdf_add_header_footer.py"
---

## Ejemplo

```python
doc = pdf_create(title="Reporte Mensual")

# Header con nombre del reporte, footer con numeracion
doc = pdf_add_header_footer(
    doc,
    header_text="Reporte de Ejecuciones — Abril 2026",
    footer_text="Pagina {n} de {total}",
    page_numbers=True,
)

# Las paginas añadidas despues tendran header y footer
doc = pdf_add_page(doc)
doc = pdf_add_text(doc, "Contenido...")
```

## Notas

Internamente configura los campos `header_text`, `footer_text` y `page_numbers` del PDFDoc. La subclase `_PDFWithHeaderFooter` de `pdf_create` lee estos campos en sus metodos `header()` y `footer()` que fpdf2 llama automaticamente en cada `add_page()`. El alias `{nb}` de fpdf2 se activa via `alias_nb_pages` y fpdf2 lo reemplaza al renderizar el PDF final. Debe llamarse antes de cualquier `pdf_add_page` para que el header/footer se aplique a todas las paginas.