Marcas y Logos (Brandings)

Los Brandings son presets reutilizables del "look & feel" corporativo que se aplica a cada PDF que sale de la plataforma. En vez de pegar el logo y los colores en cada reporte, configurás una marca una vez y después cada reporte la referencia por branding_id. Cambiar el logo es un solo click.

Resumen ejecutivo

El cambio de juego: un preset central de marca — el reporte de un cliente cambia de look sin tocar la estructura, la marca default se aplica automáticamente a todo lo que genera la plataforma.

¿Para qué sirve?

• Consistencia visual — el PDF mensual de facturación tiene exactamente el mismo header que el reporte semanal de mantenimiento.
• Multi-cliente — un proveedor de servicios de mantenimiento tiene un branding por cliente con su propio logo y colores.
• Rebrand indoloro — nueva identidad corporativa, un cambio, todo heredado.
• Default del tenant — si un reporte no especifica branding, usa el default del tenant.

¿Cómo funciona?

flowchart LR
  B[(brandings<br/>per-tenant)] -->|resolve by id| P[PDF generator]
  R1[Reporte on-demand] --> P
  R2[Reporte programado] --> P
  R3[Agente IA genera PDF] --> P
  P --> F[PDF con header/footer/<br/>logo/colores]

Cada reporte tiene dos formas de especificar branding:

1. branding_id — referencia un preset guardado. Tiene prioridad.
2. branding inline — dict con los mismos campos, pero no se guarda como preset.

Si ni una ni otra, se usa el branding con is_default=true del tenant (si existe).

Parámetros de un branding

¿Cómo usarlo?

Crear un branding

1. Administración → Marcas y Logos → Nueva.
2. Nombrarlo ("Cliente Norte").
3. Subir el logo (PNG/JPG, máximo 2 MB — el ideal son 300×100 px).
4. Escribir el nombre de empresa que va junto al logo.
5. (Opcional) Agregar líneas del header — una por línea: división, teléfono, website.
6. (Opcional) Texto derecho — ej: "Confidencial — no distribuir".
7. Elegir los colores del header y footer. El editor muestra preview en vivo.
8. (Opcional) Color de acento para los encabezados de tabla.
9. Elegir la fuente (Courier, Helvetica o Times).
10. (Opcional) Marcarlo como default del tenant.
11. Guardar.

El branding está listo para ser referenciado por reportes.

Usar un branding en un reporte

En un reporte on-demand:

• Abrir el editor de reporte.
• En el selector Branding, elegir el preset guardado.
• Generar. El PDF sale con ese look.

En un reporte programado:

• Editar el reporte programado.
• Seleccionar el branding en el campo Branding.
• La próxima ejecución lo aplica.

Desde un agente de IA:

• El agente WhatsApp o email que genera reportes puede recibir un branding_id en sus defaults. Al generar, el PDF sale con esa marca. Útil si el mismo agente atiende varios clientes con marcas distintas.

Marcar como default

El branding con is_default=true se aplica automáticamente a cualquier reporte que no especifique branding_id ni branding inline. Solo puede haber uno default por tenant — al marcar uno nuevo, el anterior se desmarca automáticamente.

Endpoints REST

POST   /api/v1/brandings          # crear
GET    /api/v1/brandings          # listar
GET    /api/v1/brandings/{id}     # detalle
PATCH  /api/v1/brandings/{id}     # actualizar
DELETE /api/v1/brandings/{id}     # borrar

Casos de uso

1 · Proveedor de servicios multi-cliente. Empresa que hace mantenimiento para 12 plantas distintas. Cada cliente tiene su branding guardado: logo, color corporativo, footer con número de contrato. Cada reporte mensual del cliente hace referencia a su branding_id. El cliente C recibe su PDF con su marca; el cliente D con la suya. Ningún trabajo humano de diseño.

2 · Rebrand corporativo. La empresa cambia de identidad visual. Nuevo logo, nueva paleta. En vez de editar los 15 templates de reportes: se edita el branding "Corporativo" y se presiona guardar. La próxima semana todos los reportes programados salen con la nueva marca.

3 · Default del tenant + un caso especial. El tenant tiene un branding "Estándar" marcado como default: se aplica a todos los reportes on-demand y programados. Un reporte específico — la auditoría anual al cliente estrella — lleva su propio branding_id con el logo co-marca. Todo lo demás hereda el default sin configurar nada.

Limitaciones y supuestos

• Un branding por tenant puede ser is_default. Marcar uno nuevo desmarca automáticamente el anterior.
• El logo debe ser público — el PDF generator hace un fetch HTTP del logo_url. Si el logo está detrás de auth o en un bucket privado, el reporte sale sin logo. Subir a GCS público o a un CDN.
• Colores hex 6 dígitos. #FFF (3 dígitos) o red (nombre) no validan. Usar #FFFFFF.
• Sin gradientes ni imágenes de fondo. Solo colores sólidos. Si querés un header gráfico, el logo es el único componente visual.
• Font families limitadas a 3. Courier / Helvetica / Times. No hay fuentes custom — son las estándar de fpdf2 para garantizar compatibilidad con cualquier lector de PDF.
• Tamaño del logo: no hay validación automática. PNGs muy grandes hacen que el PDF crezca sin mejorar la calidad. Ideal 300×100 px optimizado.

Beneficios clave

• Un preset central → consistencia visual automática en cada PDF.
• Rebrand en segundos — edita el branding, todos los futuros reportes heredan.
• Multi-cliente sin esfuerzo — un branding por cliente, el branding_id selecciona.
• Default del tenant elimina decisiones triviales al configurar un reporte nuevo.
• Preview en vivo en el editor — ves el header/footer mientras configurás.
• Compatible con reportes on-demand, programados y generados por agentes de IA.