Skip to main content
Esta guía explica cómo integrar tu plataforma con Convertix usando la API REST. La integración consta de dos flujos principales: el flujo de registro de clientes y el flujo de conversiones.

​
Requisitos previos

Antes de comenzar, necesitas:
  • Una cuenta de Convertix activa
  • Una API key válida (debes comunicarte con el equipo de Convertix para la creación de la misma)
  • Acceso a tu servidor backend para realizar las llamadas a la API

​
Verificar tu API key

Antes de comenzar la integración, puedes verificar que tu API key funciona correctamente usando el endpoint de salud: GET / - Verificación de salud de la Api Key Este endpoint te permite validar que tu API key es válida y está activa antes de realizar operaciones más complejas.

​
Flujo de registro de clientes

El flujo de registro permite crear clientes en Convertix cuando un usuario llega desde una campaña publicitaria y completa el formulario en tu landing page.

​
Pasos del flujo de registro

  1. Usuario hace clic en el anuncio: El usuario ve tu anuncio en Meta Ads o TikTok Ads y hace clic.
  2. Redirección a Landing Convertix: El usuario es redirigido a una landing page creada en Convertix, donde se captura su información inicial.
  3. Redirect a tu página: Convertix redirige al usuario a tu página con un parámetro convertixId en la URL (ejemplo: www.tudominio.com?convertixId=LD_1234ADD).
  4. Captura de información: En tu página, capturas la información adicional del usuario (nombre, email, teléfono, etc.) junto con el convertixId del query parameter.
  5. Crear cliente mediante API: Realizas una llamada al endpoint de creación de cliente con toda la información recopilada.

​
Endpoint: Crear un nuevo cliente

POST /client - Crear un nuevo cliente Campos requeridos:
  • leadReference: El convertixId obtenido del query parameter del redirect
Campos opcionales:
  • name: Nombre completo del cliente
  • email: Email del cliente
  • phoneNumber: Número de teléfono del cliente
  • externalReference: Referencia externa para identificar al cliente en tu sistema
Comportamiento importante: Si proporcionas un externalReference y ya existe un cliente con esa referencia, la API devolverá el ID del cliente existente en lugar de crear uno nuevo. Esto te permite evitar duplicados. Ejemplo de respuesta exitosa:

​
Flujo de conversión

El flujo de conversión permite registrar cuando un cliente realiza una acción valiosa (como una compra) en tu plataforma.

​
Pasos del flujo de conversión

  1. Usuario realiza acción valiosa: El usuario completa una acción importante en tu plataforma (compra, registro premium, etc.).
  2. Identificar al cliente: Identificas al cliente usando su email o clientExternalReference (la referencia externa que proporcionaste al crear el cliente).
  3. Crear conversión mediante API: Realizas una llamada al endpoint de creación de conversión con los datos de la transacción.
  4. Procesamiento automático: Convertix procesa la conversión y automáticamente dispara eventos de feedback a Meta Ads y TikTok si están configurados, optimizando tus campañas publicitarias.

​
Endpoint: Crear una conversión para un cliente

POST /client/conversion - Crear una conversión para un cliente Campos requeridos:
  • amount: Monto de la conversión
  • currency: Moneda de la conversión (USD o ARS)
Identificación del cliente (uno de los dos):
  • email: Email del cliente
  • clientExternalReference: Referencia externa del cliente
Campos opcionales:
  • conversionExternalReference: Referencia externa de la conversión para prevenir duplicados
Nota importante: Debes proporcionar al menos uno de los campos de identificación (email o clientExternalReference). Si no se proporciona ninguno o no se encuentra un cliente, se devolverá un error. Ejemplo de respuesta exitosa:

​
Autenticación

Todas las llamadas a la API requieren autenticación mediante API key. Incluye tu API key en el header de cada solicitud:

​
Manejo de errores

La API devuelve códigos de estado HTTP estándar:
  • 200: Operación exitosa
  • 201: Recurso creado exitosamente
  • 400: Solicitud incorrecta (datos inválidos)
  • 404: Recurso no encontrado
Todos los errores incluyen un mensaje descriptivo en el cuerpo de la respuesta:

​
Próximos pasos

Una vez que hayas implementado ambos flujos:
  1. Prueba la integración: Realiza pruebas con datos de prueba para asegurarte de que todo funciona correctamente.
  2. Configura eventos de Meta y TikTok: Asegúrate de tener configurados los eventos de feedback en tu cuenta de Convertix para que las conversiones se envíen automáticamente a las plataformas publicitarias.
  3. Monitorea las métricas: Revisa las métricas en tu panel de Convertix para verificar que las conversiones se están registrando correctamente.

​
Referencia completa de la API

Para más detalles sobre los endpoints, parámetros y respuestas, consulta la Referencia de la API.