TikTok para desarrolladores: recepción y seguridad
OAuth, aislamiento, mapeo, webhooks, idempotencia y procesamiento de oportunidades.
Arquitectura de recepción
OAuth autoriza los anunciantes por conexión. La sincronización identifica los formularios; cada uno se vincula con un flujo y mapeo de catálogo. El webhook registra la entrega antes del procesamiento programado. En modo operativo, el escritor confirma contacto y oportunidad; el estado processed refleja esa confirmación.
Autorización y aislamiento
Las credenciales se gestionan en el servidor y se mantienen cifradas. La recepción utiliza una URL privada con un secreto ligado a cuenta, conexión y formulario, y comprueba sus correspondencias. Este mecanismo no debe confundirse con una firma criptográfica del proveedor. No publiques la URL de recepción, ni la incluyas en código cliente o capturas.
La autorización temporal se consume una sola vez. El acceso de una cuenta no concede acceso a las demás. El procesamiento exige cuenta elegible, módulo habilitado y esquema disponible; una cuenta archivada o suspendida no crea oportunidades nuevas.
Campos e identidad
Nombre, apellidos, correo y teléfono tienen reconocimiento automático. Las preguntas adicionales se relacionan con identificadores del catálogo mediante la correspondencia JSON de la interfaz. Los identificadores externos se conservan como cadenas para evitar pérdida de precisión. Si el proveedor no entrega URL o UTM, no se fabrican esos valores.
Idempotencia y reintentos
La identidad del lead externo se comprueba en el contexto de su conexión y formulario. Repetir la entrega del mismo lead no debe crear otra oportunidad. Los errores recuperables se reintentan con espera; los casos bloqueados requieren revisión. El procesador limita trabajo por lote, cuenta y tiempo, y aísla fallos entre cuentas.
Los datos no mapeados de una entrega pendiente se conservan cifrados durante su procesamiento. La tabla de entregas muestra identificadores y estados, no el contenido personal del formulario.
Pruebas y operación
La activación operativa requiere una prueba recibida de la misma conexión y formulario. Verifica autorización, consulta de formularios, correspondencia de campos, entrega, persistencia, responsable y repetición del mismo ID. La prueba de OAuth por sí sola no demuestra el recorrido de datos.
La implementación pasó 41 pruebas automatizadas y 144 aserciones antes de su apertura general, además de una entrega real procesada automáticamente en la cuenta de pruebas. Los fallos y reintentos inducidos se comprobaron en un entorno aislado.
Alcance de esta documentación
Documenta el conector administrado desde PerformLead CRM. No es una API pública para enviar leads arbitrarios al webhook de TikTok. Para integraciones propias, consulta la documentación de desarrolladores. Events API, campañas e importación histórica son recorridos separados de la recepción descrita aquí.