Templates

Un Template es un paquete de video versionado subido a un proyecto. Contiene los assets de animación, el manifiesto de bindings y archivos de video opcionales que el Percus Player usa para renderizar videos personalizados.

Tipos de template

Tipo	Descripción
LottieStandalone	Animación Lottie/Bodymovin en JSON pura con assets estáticos opcionales
Raster	Video MP4 de base combinado con un overlay Lottie para personalización de texto e imágenes

Ciclo de vida del estado

Testing ──► Production ──► Previous
   │                           │
   └──────────────────────────►└──► Archived

Estado	Significado
Testing	Subido y disponible para pruebas internas. Aún no está en producción.
Production	El template activo servido en el canal PROD. Solo un template por proyecto puede estar en Production a la vez.
Previous	Estaba previamente en Production. Se mantiene como referencia.
Archived	Retirado. No puede eliminarse si estuvo alguna vez en Production.

Cuando un nuevo template se despliega a Production, el template Production actual se mueve automáticamente a Previous.

Subir un template

Los templates se suben como formulario multipart a:

POST /api/Projects/{projectId}/templates/upload

Campos soportados:

Campo	Tipo	Requerido	Notas
name	string	✅	Nombre del template
version	string	—	Por defecto "1.0". Formato: "major.minor"
kind	enum	✅	LottieStandalone o Raster
templateJson	archivo	—	JSON Lottie (inline, Fase 1)
manifestJson	archivo	—	JSON del manifiesto de bindings
overlayJson	archivo	—	Config del overlay (solo Raster)
videoFile	archivo	Solo Raster	Video MP4 de fondo
posterFile	archivo	—	Imagen de previsualización
assetFiles	archivo[]	—	Assets estáticos adicionales

Tamaño máximo de subida: 250 MB.

La cabecera Idempotency-Key puede establecerse para evitar subidas duplicadas en caso de reintento.

Ejemplo (curl)

curl -X POST https://api.example.com/api/Projects/{projectId}/templates/upload \
  -H "Authorization: Bearer {token}" \
  -H "Idempotency-Key: unique-upload-id" \
  -F "name=Q2 Tarjeta de crédito v1" \
  -F "kind=LottieStandalone" \
  -F "version=1.0" \
  -F "templateJson=@template.json" \
  -F "manifestJson=@manifest.json"

Desplegar a Production

El despliegue publica un template en Testing al canal de distribución PROD y lo marca como Production:

POST /api/Projects/{projectId}/templates/{templateId}/deploy

Requiere rol ProjectManager o OrganizationAdmin.

Alternativamente, publica directamente a un canal específico usando la API de Canales de distribución.

Archivar un template

POST /api/Projects/{projectId}/templates/{templateId}/archive

Un template en estado Production no puede archivarse. Primero muévelo a Previous desplegando una versión más nueva.

Previsualización

Genera una previsualización del template con datos de prueba:

POST /api/Projects/{projectId}/templates/{templateId}/preview
{ "data": { "clientName": "Ana García", "balance": "$ 15.432" } }

Devuelve una URL firmada al asset de previsualización renderizado.

Reglas de versionado

• Las versiones son inmutables. No puedes editar un template subido — sube una nueva versión en su lugar.
• El campo version es una etiqueta de visualización ("1.0", "2.0", etc.) definida por quien sube el template.
• Solo un template por proyecto puede estar en Production en un momento dado.