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

# API de Tik Tok

> Referencia interna para la integración de TikTok: devolución de llamada de OAuth, procesamiento de eventos de webhook y enrutamiento de mensajes directos.

> **Documentación interna para desarrolladores.** Esta página cubre la integración de la API de TikTok for Business: devolución de llamada de OAuth, arquitectura de webhook y enrutamiento de eventos. No está destinado a usuarios finales.

***

## Mapa de ruta

| Método     | Punto final            | Archivo de controlador     | Descripción                           |
| ---------- | ---------------------- | -------------------------- | ------------------------------------- |
| `GET`      | `/api/tiktok/callback` | `tiktok/callback/route.ts` | Devolución de llamada de TikTok OAuth |
| `GET/POST` | `/api/tiktok/route.ts` | `tiktok/route.ts`          | Registro/verificación de webhook      |
| `POST`     | `/api/tiktok/webhook`  | (a través de ruta.ts)      | Controlador de eventos de webhook     |

***

## Flujo de OAuth de TikTok

```
1. User clicks "Connect TikTok" in Integrations settings
2. Redirect to TikTok OAuth authorization URL
3. User grants permissions (DM access)
4. TikTok redirects to GET /api/tiktok/callback?code=...&state=...
5. Server exchanges code for access token
6. Token stored encrypted in DB
7. Redirect to dashboard with success message
```

**Se requieren ámbitos de OAuth:**

* `dm.conversation.readonly` — Leer mensajes directos
* `dm.conversation.write` — Enviar DM

***

## Arquitectura de webhook

TikTok envía eventos de webhook al punto final registrado para eventos de DM.

**Verificación de webhook (desafío-respuesta):**
***CÓDIGO\_BLOQUE\_1***

**Procesamiento de eventos de webhook (POST):**
***CÓDIGO\_BLOQUE\_2***

***

## Carga útil del evento DM

```json theme={null}
{
  "event": "direct_message",
  "timestamp": 1705312800,
  "data": {
    "conversation_id": "tiktok_conv_abc",
    "sender_id": "tiktok_user_xyz",
    "message": {
      "id": "msg_abc",
      "type": "text",
      "content": "Hi, I saw your product!"
    }
  }
}
```

***

## Enrutamiento de conversación

DM entrante de TikTok → identificado por `sender_id` → crear o continuar una conversación de ZappWay con `channel: 'tiktok'` → ruta al empleado de IA asignado.

***

## Variables de entorno necesarias

| Variables               | Descripción                                 |
| ----------------------- | ------------------------------------------- |
| `TIKTOK_CLIENT_KEY`     | Clave de cliente de la aplicación TikTok    |
| `TIKTOK_CLIENT_SECRET`  | Secreto del cliente de la aplicación TikTok |
| `TIKTOK_WEBHOOK_SECRET` | Para verificación de firma de webhook       |

***

## Problemas conocidos / Problemas

* **La API de TikTok es estrictamente interna**: actualmente no hay una interfaz de usuario de configuración orientada al usuario. La conexión la realiza el equipo de desarrollo en nombre de los clientes.
* **Actualización de token:** Los tokens de acceso a TikTok caducan. Un trabajo en segundo plano debe actualizarlos antes de que caduquen usando `refresh_token`.
* **Disponibilidad de DM:** El acceso a la API de DM de TikTok está restringido a cuentas comerciales aprobadas. La aplicación debe estar incluida en la lista blanca de TikTok.
* **Límites de tarifas:** TikTok impone límites estrictos de tarifas por cuenta comercial. Supervise las respuestas `429`.