> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertixapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integración con API
> Guía para integrar tu plataforma con Convertix usando la API REST.
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](/api-reference/health/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.
```mermaid theme={null}
flowchart LR
A[ADS] --> B[Usuario]
B --> C[Landing Convertix]
C --> D[Página Cliente
Redirect con query param
Ej: www.paginacliente.com?convertixId=LD_1234]
D --> E[Cliente guarda información
del usuario con convertixId]
E --> F[POST /client
Crear nuevo cliente]
F --> G[Cliente creado
con ID]
style F fill:#16A34A,stroke:#15803D,color:#fff
style G fill:#07C983,stroke:#16A34A,color:#fff
```
### 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](/api-reference/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:**
```json theme={null}
{
"id": 12345
}
```
## 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.
```mermaid theme={null}
flowchart LR
A[Usuario carga en
plataforma del cliente] --> B[Cliente identifica
usuario por email
o externalReference]
B --> C[POST /client/conversion
Crear conversión]
C --> D[Convertix procesa
la conversión]
D --> E[Métricas internas +
Optimización en
Facebook/TikTok Ads]
style C fill:#16A34A,stroke:#15803D,color:#fff
style E fill:#07C983,stroke:#16A34A,color:#fff
```
### 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](/api-reference/client/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:**
```json theme={null}
{
"id": 67890,
"leadId": 12345
}
```
## Autenticación
Todas las llamadas a la API requieren autenticación mediante API key. Incluye tu API key en el header de cada solicitud:
```
x-api-key: tu-api-key-aqui
```
## 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:
```json theme={null}
{
"message": "Descripción del error"
}
```
## 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](/api-reference/client/crear-un-nuevo-cliente).