TotalPlay.cl | Documentación API e integración

1. Introducción

Este documento es una guía técnica oficial para clientes o integradores que necesitan interactuar de forma directa con la API de la plataforma utilizando el API_TOKEN de un tenant.

Todos los ejemplos expuestos en este manual asumen que las peticiones se realizan contra la URL base de producción indicada arriba.

2. Cómo se Autentica

El token lo genera un super administrador desde el panel de administración. Cada petición HTTP hacia los endpoints protegidos debe incluir las siguientes cabeceras:

Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Reglas de Seguridad:

No intentes operar sobre recursos de otro tenant (retornará 403).
En endpoints de creación (ej. POST /users), el parámetro tenant_id es opcional.
Si envías explícitamente el tenant_id, este debe coincidir con el del token.

3. Flujo Recomendado de Integración

Para establecer una integración limpia y evitar errores de claves foráneas, sigue este orden estrictamente:

Crear servidores: Define la infraestructura base.
Crear categorías: Agrupa el contenido por servidor.
Crear canales o contenidos: Asigna los canales a las categorías.
Crear planes: Estructura tu oferta comercial.
Asignar canales a planes: Define qué se puede ver en cada plan.
Crear usuarios: Registra a los clientes finales indicando el límite de pantallas.
Asignar planes y servidores: Otorga permisos de acceso a los usuarios.

4. CRUD Disponible con Token

Tu API_TOKEN te permite operar sobre las siguientes rutas base:

/servers

/categories

/channels

/plans

/users

/peliculas

/monitor

/audit-logs

5. Ejemplos de Gestión (Endpoints Administrativos)

A continuación, se detallan las operaciones completas (CRUD) para cada una de las entidades principales de la plataforma.

Tipos de Contenido Permitidos

Al gestionar Categorías y Canales, es obligatorio enviar el campo tipo_contenido. Los únicos valores válidos (sensibles a mayúsculas/minúsculas) son:

TV: Canales de transmisión en vivo (Live TV).
Pelicula: Contenido de video bajo demanda (VOD).
Serie: Contenedores de series y capítulos.

⚠️ Regla de Consistencia: Al crear o asignar un contenido a una categoría, ambos deben tener exactamente el mismo tipo_contenido. Por ejemplo, la API rechazará que intentes asignar un contenido de tipo "TV" a una categoría de tipo "Pelicula".

Gestión de Servidores

1. Crear un Servidor

curl -X POST "https://app.totalplay.cl/api/servers" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Servidor Principal",
    "servidor_base_url": "http://linea1.ejemplo.com:8080",
    "default_epg_source_url": "https://epg.ejemplo.com/guide.xml",
    "status": true
  }'

2. Listar Servidores

curl -X GET "https://app.totalplay.cl/api/servers?status=true&withCounts=true" \
  -H "Authorization: Bearer $API_TOKEN"

3. Obtener un Servidor por ID

curl -X GET "https://app.totalplay.cl/api/servers/15" \
  -H "Authorization: Bearer $API_TOKEN"

4. Actualizar un Servidor

curl -X PATCH "https://app.totalplay.cl/api/servers/15" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Servidor Principal Madrid"
  }'

5. Eliminar un Servidor

Nota: Solo se puede eliminar si no tiene usuarios asignados.

curl -X DELETE "https://app.totalplay.cl/api/servers/15" \
  -H "Authorization: Bearer $API_TOKEN"

Gestión de Categorías

1. Crear una Categoría

curl -X POST "https://app.totalplay.cl/api/categories" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": 15,
    "name": "Peliculas Accion",
    "tipo_contenido": "Pelicula",
    "status": true
  }'

2. Listar Categorías

curl -X GET "https://app.totalplay.cl/api/categories?server_id=15&withCounts=true" \
  -H "Authorization: Bearer $API_TOKEN"

3. Actualizar una Categoría

curl -X PATCH "https://app.totalplay.cl/api/categories/33" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Peliculas de Accion HD"
  }'

4. Eliminar una Categoría

curl -X DELETE "https://app.totalplay.cl/api/categories/33" \
  -H "Authorization: Bearer $API_TOKEN"

Gestión de Canales

⚠️ Importante sobre el campo `status` en la creación:

Para crear contenido en POST /channels (sea TV, Película, Serie Contenedora o Episodio), NO envíes el campo status. El endpoint no lo admite en el DTO de creación y retornará un error.

El contenido se crea activo por defecto. Si después necesitas desactivarlo o cambiar su estado, debes usar los endpoints de actualización:

PATCH /channels/:id enviando {"status": false} en el body.
O usando el acceso rápido: PATCH /channels/:id/toggle-status.

1. Crear Contenido (Diferenciado por Tipo)

A. Crear Canal de TV (En Vivo)

curl -X POST "https://app.totalplay.cl/api/channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 33,
    "name": "Canal Deportes HD",
    "url": "http://cdn.ejemplo.com/live/deportes-hd.m3u8",
    "tipo_contenido": "TV"
  }'

B. Crear Película (VOD)

curl -X POST "https://app.totalplay.cl/api/channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 34,
    "name": "Misión en la Selva",
    "url": "http://cdn.ejemplo.com/movie/mision-selva.m3u8",
    "tipo_contenido": "Pelicula"
  }'

C. Crear Serie (Contenedor + Episodios)

Para las series, la creación funciona en dos pasos esenciales:

Paso 1: Serie Contenedora

Esto crea la serie "visual", sin stream propio. Es la forma correcta para que luego no se cuenten los capítulos como contenidos separados en las estadísticas.

curl -X POST "https://app.totalplay.cl/api/channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 17,
    "name": "Horizonte Rojo",
    "tipo_contenido": "Serie",
    "is_series_container": true,
    "series_name": "Horizonte Rojo",
    "url_imagen": "https://cdn.example.com/posters/horizonte-rojo.jpg"
  }'

Notas del contenedor:

No mandes url.
No mandes parent_series_id.
No mandes season_number ni episode_number.
series_name puede omitirse si es igual a name, pero se recomienda mandarlo.

Paso 2: Episodio

Primero tomas el ID de la serie contenedora creada arriba (supongamos que fue 120).

curl -X POST "https://app.totalplay.cl/api/channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 17,
    "name": "Horizonte Rojo T1E1",
    "url": "http://vod.example.com/series/horizonte-rojo/t1e1.m3u8",
    "tipo_contenido": "Serie",
    "parent_series_id": 120,
    "series_name": "Horizonte Rojo",
    "season_number": 1,
    "episode_number": 1,
    "episode_title": "Cruce en la Niebla"
  }'

2. Listar Canales

curl -X GET "https://app.totalplay.cl/api/channels?category_id=33&page=1&limit=50" \
  -H "Authorization: Bearer $API_TOKEN"

3. Actualizar un Canal

curl -X PATCH "https://app.totalplay.cl/api/channels/101" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Misión en la Selva (Remasterizada)",
    "status": false
  }'

4. Cambiar Estado Rápidamente

curl -X PATCH "https://app.totalplay.cl/api/channels/101/toggle-status" \
  -H "Authorization: Bearer $API_TOKEN"

5. Eliminar un Canal

curl -X DELETE "https://app.totalplay.cl/api/channels/101" \
  -H "Authorization: Bearer $API_TOKEN"

Gestión de Planes y Asignaciones

1. Crear un Plan

curl -X POST "https://app.totalplay.cl/api/plans" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Premium",
    "description": "Plan completo"
  }'

2. Listar Planes

curl -X GET "https://app.totalplay.cl/api/plans?withCounts=true" \
  -H "Authorization: Bearer $API_TOKEN"

3. Asignar Canales al Plan

curl -X POST "https://app.totalplay.cl/api/plans/10/assign-channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_ids": [101, 102, 103]
  }'

4. Remover Canales de un Plan

curl -X POST "https://app.totalplay.cl/api/plans/10/remove-channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_ids": [102]
  }'

5. Eliminar un Plan

curl -X DELETE "https://app.totalplay.cl/api/plans/10" \
  -H "Authorization: Bearer $API_TOKEN"

Gestión de Usuarios IPTV

Nota 1: La variable max_simultaneous_views es crítica. Define cuántas reproducciones simultáneas (concurrencia) puede tener el usuario.

Nota 2: El campo username debe ser obligatoriamente una dirección de correo electrónico válida.

1. Crear un Usuario

curl -X POST "https://app.totalplay.cl/api/users" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "cliente_vip@correo.com",
    "password": "ClaveSegura123",
    "status": true,
    "max_simultaneous_views": 2,
    "server_ids": [15, 16]
  }'

2. Listar Usuarios

curl -X GET "https://app.totalplay.cl/api/users?withServers=true&withPlans=true" \
  -H "Authorization: Bearer $API_TOKEN"

3. Actualizar Usuario

curl -X PATCH "https://app.totalplay.cl/api/users/44" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": true,
    "max_simultaneous_views": 3
  }'

4. Asignar Planes a un Usuario

curl -X POST "https://app.totalplay.cl/api/users/44/assign-plans" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_ids": [10, 11]
  }'

5. Remover Planes de un Usuario

curl -X POST "https://app.totalplay.cl/api/users/44/remove-plans" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_ids": [11]
  }'

6. Asignar / Desasignar Servidores

# Asignar nuevos servidores
curl -X POST "https://app.totalplay.cl/api/users/44/assign-servers" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "server_ids": [17] }'

# Remover servidores
curl -X POST "https://app.totalplay.cl/api/users/44/unassign-servers" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "server_ids": [15] }'

7. Eliminar un Usuario

curl -X DELETE "https://app.totalplay.cl/api/users/44" \
  -H "Authorization: Bearer $API_TOKEN"

6. Consumo desde Apps Cliente

Las aplicaciones que consumen el contenido no utilizan el API_TOKEN administrativo. Utilizan endpoints específicos para autenticar al usuario final e informar de su actividad.

Endpoint Principal: /api/auth/resolve

Este endpoint valida las credenciales del usuario final y retorna la estructura jerárquica de contenido disponible.

POST /api/auth/resolve
{
  "tenant_id": 3,
  "username": "cliente_vip@correo.com",
  "password": "ClaveSegura123"
}

Control de Concurrencia: /api/activity/ping

Para controlar el uso de pantallas simultáneas, la app cliente debe enviar "latidos" (pings) cada 30-60 segundos.

POST /api/activity/ping
{
  "user_id": 44,
  "channel_id": 101,
  "device_id": "smart-tv-sala-123",
  "device_type": "android"
}

Activity Tracker Limit Reached

Si el usuario excede sus max_simultaneous_views, el endpoint responderá con ok: false y reason: "SIMULTANEOUS_SCREEN_LIMIT_REACHED". La aplicación debe detener la reproducción.

7. Series y Catálogo

Las series se exponen como un contenido contenedor.
Una serie no debe contarse como muchos canales por cada episodio.
Los episodios siguen existiendo para navegación y reproducción.
En listados generales y conteos, la serie aparece como un solo contenido.

8. Errores Comunes

400 Bad Request

Normalmente indica datos inválidos (ej. server_ids vacío al crear usuario, nombre duplicado, URL inválida).

401 Unauthorized

Token inválido, usuario IPTV inválido en auth/resolve, o límite de pantallas simultáneas alcanzado.

403 Forbidden

Normalmente indica un intento de operar fuera del tenant asignado al token.

9. Recomendaciones Prácticas

Usa siempre servidor_base_url; xtream_base_url solo queda como alias legacy.
No dependas de tenant_id en endpoints de creación cuando ya trabajas con API_TOKEN.
Crea primero la estructura: Server → Category → Channel.
Crea usuarios al final, asegurándote de usar server_ids y max_simultaneous_views correctos.

10. Contacto y Soporte

Si tienes dudas adicionales, problemas técnicos con la integración o necesitas escalar un caso, puedes comunicarte con nuestro equipo de soporte técnico a través de los siguientes canales:

Correo Electrónico

contacto@totalplay.cl

Teléfono / WhatsApp

+56 9 2747 1062