# Proceso de Recolección de Estadísticas de Marketing

### 🧠 Contexto General

El proceso descrito tiene como objetivo centralizar y automatizar la recolección de estadísticas de marketing digital desde plataformas como **Meta Ads**, **Google Ads**, **Adsterra**, entre otras, para ser almacenadas y analizadas en el sistema **Commizzion** de Inlaze.

Esto permite mantener actualizadas las métricas claves de desempeño en marketing digital tales como clics únicos, gastos por campaña, y fuentes de tráfico, alineadas con las campañas activas y su nomenclatura estandarizada.

***

### 🔗 Integraciones y Componentes Clave

* **Airbyte**: Herramienta de ETL que conecta con fuentes como Meta y Google Ads.
* **Airflow + Python**: Se utiliza para orquestar y ejecutar cada 2 horas un DAG que extrae, transforma y guarda la información.
* **AWS S3**: Se utiliza para almacenamiento temporal de los archivos CSV generados por Airbyte.
* **Commizzion API**: Expone el endpoint para almacenar los datos procesados.
* **Repositorio `api-ads-integration`**: Contiene el código de transformación y envío de datos.

***

### 📅 Flujo de Proceso

#### 1. Nomenclatura de Campañas

Para poder asociar una campaña a un link en Commizzion, todas deben seguir esta nomenclatura:

```
COD [linkId] - [PromCode] - [Nombre de campaña]
```

* Ejemplo: `COD 1225 - PROMX - Meta Julio Campaña`
* Si la nomenclatura no coincide, el sistema lanza un **logger warning**, y se planea integrar notificaciones por correo/Teams.

#### 2. Extracción desde Airbyte

* Airbyte se conecta a la API de cada plataforma.
* Genera archivos `.csv` con nombre:

```
{bucket}/airbyte/{traffic_source}/{YYYY_MM_DD}_{executionNumber}.csv
```

Ejemplo: `airbyte/meta_ads_insights/2025_07_10_7.csv` (7ma ejecución del 10 de julio de 2025).

* Se extrae información sólo del **día actual y anterior**. Esto se logra modificando automáticamente la configuración del conector (no soportado vía interfaz).

#### 3. Transformación (Airflow + Python)

Cada 2 horas, el DAG:

* Detecta el último archivo del día por fuente.
* Mapea los headers del CSV (difieren entre fuentes).
* Extrae:
  * `date`
  * `linkId`
  * `uniqueClickCount`
  * `clickCount`
  * `totalSpend`
  * `currency` (convertido a USD si aplica)
  * `trafficSource`
* Si hay múltiples filas por campaña, se **agrupan y suman** las métricas.

#### 4. Conversión de Moneda

* Se usa la última tasa guardada en la base de datos de Inlaze.
* Se consulta vía API Commizzion.
* El microservicio de conversión asegura persistencia incluso si falta tasa exacta por fecha.

#### 5. Carga Final en Commizzion

Se hace un POST al endpoint:

```
POST /api/v1/admin/marketing/update-purchases
```

Payload de ejemplo:

```json
{
  "data": [
    {
      "date": "2025-06-13",
      "totalSpend": 100,
      "currency": "USD",
      "linkId": 1225,
      "clickCount": 50,
      "uniqueClickCount": 10,
      "trafficSource": "GOOGLE"
    }
  ]
}
```

Este endpoint hace un **upsert** usando la combinación `date + linkId + trafficSource` como clave.

***

### ⚡ Frecuencia y Ejecución

* Se ejecuta **cada 2 horas** por Airflow.
* Se procesan solo los archivos más recientes del día por fuente.

***

### 🚧 Validaciones y Tolerancia a Fallos

* Logger para nomenclatura malformada.
* Validación de columnas obligatorias y valores nulos.
* Merge de filas por campaña (suma de métricas).
* Airflow tiene reintentos configurados por defecto.
* Logs disponibles en Airflow UI para trazabilidad.

***

### 📊 Esquema de Base de Datos

Los datos se insertan en la tabla `marketing_performance` del esquema `affiliate`. Campos relevantes:

| Campo                | Tipo      | Descripción                        |
| -------------------- | --------- | ---------------------------------- |
| `date`               | `date`    | Fecha del registro                 |
| `link_id`            | `bigint`  | ID de enlace (extraído del nombre) |
| `click_count`        | `bigint`  | Total de clics                     |
| `unique_click_count` | `bigint`  | Clics únicos                       |
| `total_spend`        | `numeric` | Gasto total en publicidad          |
| `currency`           | `varchar` | Siempre USD                        |
| `traffic_source`     | `varchar` | Fuente (META, GOOGLE, etc.)        |

***

### 🔹 Consideraciones Finales

* El flujo es modular y extensible a nuevas fuentes.
* Se desacopla extracción, procesamiento y almacenamiento.
* Se prioriza trazabilidad, integridad de datos y facilidad de mantenimiento.
* Planeado: notificación automática ante errores en nomenclatura de campaña.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-affiliates.inlaze.com/reportes/proceso-de-recoleccion-de-estadisticas-de-marketing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.