# Sincronización de audiencias

> Sincronice listas de contactos con plataformas publicitarias (Meta, LinkedIn, Google Ads, X) de forma recurrente

Source: https://docs.graph8.com/es/developers/audience-syncs/

> **Tip: ¿Usa el SDK o el CLI?**
> El [SDK de JavaScript](https://docs.graph8.com/developers/sdk/) y el [CLI](https://docs.graph8.com/developers/cli/) encapsulan estos endpoints. Los comandos del CLI son `g8 audience-syncs list`, `g8 audience-syncs create` y `g8 audience-syncs trigger`.

Las sincronizaciones de audiencias envían una audiencia de graph8 (lista de contactos) a una plataforma publicitaria y la mantienen actualizada de forma periódica. graph8 es compatible con cuatro plataformas: **Meta** (audiencias personalizadas de Facebook/Instagram), **LinkedIn** (Matched Audiences), **Google Ads** (Customer Match) y **X** (Tailored Audiences).

Cada configuración de sincronización tiene un **modo**:

- `mirror`: mantiene la audiencia de la plataforma sincronizada exactamente con la lista de origen (agrega nuevos miembros y elimina los que ya no están).
- `append_only`: solo agrega nuevos miembros; nunca elimina.

Un proceso ejecuta cada sincronización según su `refresh_cadence_hours`. También puede activar una sincronización de forma manual.

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/audience-syncs` | GET | Lista todas las configuraciones de sincronización de la organización |
| `/audience-syncs` | POST | Crea una nueva configuración de sincronización |
| `/audience-syncs/{id}` | GET | Obtiene una configuración de sincronización individual |
| `/audience-syncs/{id}` | PATCH | Actualiza una configuración de sincronización |
| `/audience-syncs/{id}` | DELETE | Eliminación lógica de una configuración de sincronización |
| `/audience-syncs/{id}/trigger` | POST | Activa manualmente una ejecución de sincronización |
| `/audience-syncs/{id}/runs` | GET | Lista las ejecuciones de sincronización recientes |
| `/audience-syncs/{id}/errors` | GET | Lista únicamente las ejecuciones de sincronización fallidas |

Para esquemas en formato legible por máquina, consulte la [documentación interactiva de la API](https://be.graph8.com/api/v1/docs).

---

## Listar sincronizaciones de audiencias

`GET /audience-syncs`

Devuelve todas las configuraciones de sincronización de la organización autenticada.

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/audience-syncs" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(
    f"{BASE_URL}/audience-syncs",
    headers=HEADERS,
)
configs = response.json()["data"]
```

### Respuesta

```json
{
  "data": [
    {
      "id": 12,
      "audience_id": 5,
      "platform": "meta",
      "platform_audience_name": "Q2 Outbound - Mirror",
      "mode": "mirror",
      "refresh_cadence_hours": 24,
      "is_active": true,
      "status": "active",
      "last_sync_at": "2026-04-15T08:00:00Z",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ]
}
```

---

## Crear sincronización de audiencia

`POST /audience-syncs`

Crea una nueva configuración de sincronización. Devuelve `409 Conflict` si ya existe una configuración para la misma combinación de `audience_id` + `platform`.

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `audience_id` | integer | **Sí** | ID de la lista de origen (debe ser > 0) |
| `platform` | string | **Sí** | Uno de `meta`, `linkedin`, `google`, `x` |
| `platform_audience_name` | string | No | Nombre visible en la plataforma publicitaria (máx. 255) |
| `mode` | string | No | `mirror` (predeterminado) o `append_only` |
| `refresh_cadence_hours` | integer | No | 0-720, predeterminado 24 |
| `platform_config` | object | No | Configuración específica de la plataforma (p. ej., ID de cuenta publicitaria, alcances OAuth) |
| `suppression_list_ids` | integer[] | No | Listas cuyos miembros deben excluirse |

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/audience-syncs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": 5,
    "platform": "meta",
    "platform_audience_name": "Q2 Outbound",
    "mode": "mirror",
    "refresh_cadence_hours": 24,
    "platform_config": {"ad_account_id": "act_1234567890"}
  }'
```

**Python**

```python
response = requests.post(
    f"{BASE_URL}/audience-syncs",
    headers=HEADERS,
    json={
        "audience_id": 5,
        "platform": "meta",
        "platform_audience_name": "Q2 Outbound",
        "mode": "mirror",
        "refresh_cadence_hours": 24,
        "platform_config": {"ad_account_id": "act_1234567890"},
    },
)
```

### Respuesta `201 Created`

Devuelve la misma estructura que un elemento de la lista.

### Errores

| Estado | Significado |
|--------|-------------|
| `409` | Ya existe una configuración de sincronización para esta combinación de audiencia + plataforma |
| `422` | `platform` no está en el conjunto permitido, o `mode` no es válido |

---

## Obtener sincronización de audiencia

`GET /audience-syncs/{config_id}`

Devuelve una configuración de sincronización individual por ID.

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/audience-syncs/12" \
  -H "Authorization: Bearer $API_KEY"
```

### Errores

| Estado | Significado |
|--------|-------------|
| `404` | Configuración de sincronización no encontrada |

---

## Actualizar sincronización de audiencia

`PATCH /audience-syncs/{config_id}`

Actualización parcial. Envíe únicamente los campos que desea modificar.

### Cuerpo de la solicitud

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `mode` | string | `mirror` o `append_only` |
| `refresh_cadence_hours` | integer | 0-720 |
| `is_active` | boolean | Pausar o reanudar sin eliminar |
| `suppression_list_ids` | integer[] | Reemplaza el conjunto de listas de supresión |

### Ejemplo

**cURL**

```bash
curl -X PATCH "https://be.graph8.com/api/v1/audience-syncs/12" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

---

## Eliminar sincronización de audiencia

`DELETE /audience-syncs/{config_id}`

Eliminación lógica. La audiencia **no** se elimina de la plataforma publicitaria; graph8 simplemente deja de sincronizarla.

### Respuesta

```json
{ "data": { "status": "deleted", "id": 12 } }
```

---

## Activar sincronización de audiencia

`POST /audience-syncs/{config_id}/trigger`

Ejecuta la sincronización de inmediato, fuera de su cadencia programada. Devuelve el resultado de la sincronización (recuentos de miembros agregados y eliminados).

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/audience-syncs/12/trigger" \
  -H "Authorization: Bearer $API_KEY"
```

### Errores

| Estado | Significado |
|--------|-------------|
| `500` | La plataforma publicitaria subyacente devolvió un error. Consulte `/runs` o `/errors` para ver el mensaje |

---

## Listar ejecuciones de sincronización

`GET /audience-syncs/{config_id}/runs`

Devuelve las ejecuciones recientes de una configuración (tanto exitosas como fallidas).

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `limit` | integer | 20 | Máximo de ejecuciones a devolver (1-100) |

### Respuesta

```json
{
  "data": [
    {
      "id": 4521,
      "started_at": "2026-04-15T08:00:00Z",
      "finished_at": "2026-04-15T08:00:14Z",
      "status": "success",
      "members_added": 12,
      "members_removed": 3,
      "total_members": 1450,
      "error_message": null
    }
  ]
}
```

---

## Listar errores de sincronización

`GET /audience-syncs/{config_id}/errors`

Misma estructura que `/runs`, filtrada por `status = "failed"`. Use este endpoint para mostrar fallas en su panel.

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `limit` | integer | 20 | Máximo de errores a devolver (1-100) |

### Respuesta

```json
{
  "data": [
    {
      "id": 4520,
      "started_at": "2026-04-15T07:30:00Z",
      "error_message": "Meta API: invalid access token",
      "details": { "config_id": 12, "status": "failed" }
    }
  ]
}
```