> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Primera activación CDP de extremo a extremo: ingest → resolución → segmento → envío

> Un recorrido completo por el bucle CDP en una sola sesión: conectar una fuente firmada, resolver identidades, construir un segmento sobre eventos resueltos, activarlo hacia una red publicitaria o un sink webhook y confirmar la sincronización — con el presupuesto de latencia que sirve de brújula de diagnóstico.

# Primera activación CDP de extremo a extremo

El CDP tiene cuatro fases — ingest, resolución de identidad, segmentación y activación — y cada una cuenta con su propia guía que profundiza en su propia superficie. Lo que ninguna hace por sí sola es acompañarle en un pase continuo: enviar un evento, verlo coserse a una persona, construir una audiencia sobre ese historial y empujar la audiencia a un destino contra el que gastar presupuesto. Este tutorial hace ese pase una vez, de principio a fin, en una sola sesión.

Haga este recorrido primero. Una vez que el bucle esté en servicio, las guías de fase se convierten en sus referencias de profundización:

* [Consola de integración CDP: fuente y destinos](https://docs.orbit.devotel.io/guides/cdp-source-and-destinations.md) — el ciclo de vida completo del secreto de ingest y de los destinos.
* [Cargar datos CDP por lotes desde archivos](https://docs.orbit.devotel.io/guides/cdp-file-ingest.md) — la vía bulk sin SDK para migraciones, onboarding y backfills.
* [Catálogo de datos CDP y reglas de identidad](https://docs.orbit.devotel.io/guides/cdp-data-catalog-and-identity-rules.md) — formas de coincidencia, prioridades, supervivencia.
* [Audiencias CDP: construir segmentos](https://docs.orbit.devotel.io/guides/cdp-segments.md) — el vocabulario completo de filtros, traits y puntuación.
* [Pipelines de activación de audiencias](https://docs.orbit.devotel.io/guides/audience-activation-pipeline.md) — cadencias, deltas, holdouts y resolución de problemas por plataforma.
* [Reverse ETL CDP y exportaciones a warehouse](https://docs.orbit.devotel.io/guides/cdp-reverse-etl-and-warehouse-exports.md) — cuando el destino es un warehouse, no una red publicitaria ni un webhook.

## Por qué importa un solo pase de extremo a extremo

Cada guía de fase da por sentado que existen las demás. Leídas por separado, le dejan coser el bucle a usted: la guía de fuente explica cómo aceptar eventos pero no qué hacer una vez que aterrizan; la guía de segmentos asume perfiles resueltos y eventos limpios; la guía de activación asume un segmento que merezca publicarse. Los workspaces CDP nuevos fracasan en los huecos entre guías — eventos ingestados pero nunca cosidos, segmentos construidos sobre duplicados sin resolver, activaciones que publican membresías exiguas que nadie diagnosticó aguas arriba.

Ejecute este pase contra una fuente de prueba y un destino de prueba antes de abrir el tráfico real. Cuando algo se desvíe más adelante, reentrará en la guía de fase de esa fase — pero reentrará sabiendo qué fase está rota, porque ha visto el bucle completo sano una vez.

## 1. Requisitos previos

Tenga los tres antes del primer evento:

1. **Un tracking plan publicado.** Declare los eventos que enviará su aplicación y la forma de propiedades por evento, en modo de aplicación `soft`, en la superficie de [tracking plan](https://docs.orbit.devotel.io/guides/cdp-tracking-plan.md). El modo soft registra las violaciones sin rechazar eventos, de modo que un productor nuevo nunca se detiene en un desajuste mientras usted itera. Apriete a `strict` más adelante.
2. **Una fuente conectada.** Un secreto de ingest emitido en **Integrations → CDP → Source (inbound)** y desplegado en su aplicación — la [guía de fuente y destinos](https://docs.orbit.devotel.io/guides/cdp-source-and-destinations.md) recorre la emisión y la rotación. Su aplicación publica eventos firmados en `https://api.orbit.devotel.io/cdp/v1/<ingest_id>/track`.
3. **Un destino con credenciales.** Una audiencia de red publicitaria alcanzada mediante una conexión OAuth, o un sink webhook HTTPS que usted controle. Conecte las credenciales antes de necesitarlas — la fase de activación solo mapea un segmento sobre un destino que ya autentica.

Tenga además una clave API con rol **owner, admin o developer**. Cada mutación de este recorrido (reglas, segmentos, activaciones) está restringida a esos roles; las lecturas aceptan más.

## 2. Ingestar una fuente

Elija un tipo de fuente en **Integrations → CDP** — Segment, RudderStack, un webhook genérico o su propio SDK publicando directamente. Emita el secreto de ingest desde la pestaña **Source (inbound)**, despliéguelo en la aplicación y firme cada petición según la [guía de firmado de ingest](https://docs.orbit.devotel.io/guides/cdp-ingest-signing.md): las tres cabeceras `X-Orbit-CDP-Timestamp`, `X-Orbit-CDP-Nonce` y `X-Orbit-CDP-Signature` sobre `<timestamp>.<nonce>.<raw body>`, con clave en el secreto en claro.

Dispare un evento `track` desde la aplicación. Después confirme que aterrizó — nunca lo suponga:

1. Abra **Integrations → CDP → Event debugger**.
2. Filtre **Type = track** y haga coincidir el nombre de su evento.
3. Expanda la fila y lea exactamente las `properties` y el `context` que guardó la pasarela.

Si falta la fila, el fallo está en la capa de firma (un 401 que la aplicación tragó) o el tracking plan está rechazando el payload — la [guía de event debugger y DLQ](https://docs.orbit.devotel.io/guides/cdp-event-debugger-and-dlq.md) cubre ambos, incluida la lectura de un cuerpo de payload derramado o perdido. No avance hasta ver aquí un evento real.

> [!NOTE]
>
> Cuando el consentimiento gobierna su ingest — por ejemplo, si
> propiedades de evento proceden de campos de contacto cubiertos por una
> limitación de finalidad — registre la base jurídica por contacto mediante
> la [API de consentimiento](https://docs.orbit.devotel.io/compliance/consent-management.md) antes de
> encender la fuente. Orbit facilita el registro pero no sustituye un
> consentimiento válido: usted sigue siendo responsable de lo que ingesta
> y del uso que le da. Esta página no es asesoría jurídica.

## 3. Resolver la identidad

Los eventos llegan con la `userId` que envió su SDK, sea cual sea. Que esa se cosa a un contacto — y a qué contacto — lo deciden las reglas de identidad, no el evento en sí. La regla por defecto resuelve `userId` solo contra identificadores externos; una `userId` con forma de email o de teléfono no se cose hasta que usted habilite esa forma de coincidencia.

1. Abra **Integrations → CDP → Identity resolution** y revise las formas de coincidencia: `External ID` (sembrada, prioridad 100), más `Phone`, `Email` y `Anonymous ID` en opt-in.
2. Si sus eventos portan email o teléfono como identidad, **simule primero** en **Audience → Identity resolution** — el dashboard se niega a guardar un cambio en esas formas hasta que una simulación haya corrido en su sesión, porque una forma demasiado amplia cose a personas equivocadas de forma irreversible. Lea el recuento estimado de fusiones; si sobre-fusiona, estreche la forma o suba su prioridad.
3. Guarde el conjunto de reglas de vuelta en la página CDP y, en el mismo constructor, fije la política de supervivencia (qué valor gana una fusión por campo).
4. Confirme que la resolución aterrizó: abra **Audience → Identity resolution** y compruebe que la identidad de su evento de prueba se plegó en un solo contacto, no en un duplicado en la cola de revisión. La [guía de catálogo de datos y reglas de identidad](https://docs.orbit.devotel.io/guides/cdp-data-catalog-and-identity-rules.md) cubre prioridades, la puerta de simulación y la separación entre política y cola de revisión.

No omita nada aquí: cada segmento de abajo lee contactos resueltos, así que los duplicados sin resolver sobreviven en cada recuento de audiencia que construya.

## 4. Construir el segmento sobre eventos resueltos

Con eventos aterrizando e identidades cosiéndose, construya la audiencia. Un segmento es un filtro guardado sobre atributos de contacto, campos personalizados y eventos de comportamiento; créelo con `POST /api/v1/contacts/segments`. Dos ejemplos trabajados — un filtro simple y un trait SQL que lo alimenta.

### Un filtro de comportamiento trabajado

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/contacts/segments \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Activated trial users",
    "description": "Trials who completed onboarding in the last 14 days",
    "filters": {
      "and": [
        { "field": "lifecycle_stage", "op": "equals", "value": "trial" },
        { "field": "event.Onboarding Completed", "op": "performed_event", "value": { "within": "14d" } },
        { "field": "event.Payment Failed", "op": "did_not_perform_event", "value": { "within": "14d" } }
      ]
    },
    "auto_refresh": true,
    "auto_refresh_interval_minutes": 720
  }'
```

Tres puntos a notar. Los eventos se referencian con el prefijo `event.<name>` y se emparejan con un operador de comportamiento — `performed_event`, `did_not_perform_event`, `event_count` o `performed_sequence` para recorridos ordenados. La ventana `within` es relativa, así que «los últimos 14 días» no exige aritmética de timestamps. Y `auto_refresh` materializa la membresía en una cadencia — la activación del paso siguiente lee esa membresía materializada, así que fíjelo.

Dimensione el filtro antes de guardarlo. `POST /api/v1/contacts/segments/preview` evalúa el mismo filtro contra datos en vivo y devuelve un recuento de coincidencias sin persistir; un recuento de cero o «todo el tenant» significan ambos que el filtro está mal, no los datos.

### Un trait SQL concreto que alimenta el segmento

Cuando el dato que necesita ya existe como SQL de warehouse — una vista de LTV propiedad de finanzas, un modelo dbt — adóptelo como [trait SQL](https://docs.orbit.devotel.io/guides/cdp-sql-traits.md) en vez de reconstruirlo en el DSL de predicados. Un único `SELECT` de solo lectura que devuelve `(user_id, trait_value)`, ejecutado a su cadencia, estampa cada valor en el mapa de traits del contacto:

```sql theme={null}
SELECT user_id,
  CASE
    WHEN SUM(amount_usd) >= 1000 THEN 'high'
    WHEN SUM(amount_usd) >= 100  THEN 'mid'
    ELSE 'low'
  END AS trait_value
FROM analytics.orders
WHERE ordered_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 365 DAY)
GROUP BY user_id
```

Una vez materializado el trait, se segmenta como cualquier atributo — `{ "field": "traits.ltv_tier", "op": "equals", "value": "high" }` se combina libremente con las condiciones de comportamiento de arriba. El árbol completo de elección de motor (predicado DSL, SQL, AI) está en la página de traits SQL; el vocabulario completo de filtros está en la [guía de segmentos](https://docs.orbit.devotel.io/guides/cdp-segments.md).

## 5. Activar hacia un destino

La activación publica el segmento donde gana presupuesto — la audiencia de una red publicitaria o su sink webhook — en una cadencia que usted controla. Recórrala en dos llamadas, según la [guía de pipeline de activación](https://docs.orbit.devotel.io/guides/audience-activation-pipeline.md).

Conecte el destino una vez. Para una red publicitaria (se muestra Google; Meta, TikTok, LinkedIn y el resto del catálogo se comportan igual):

```bash theme={null}
curl -X PATCH https://api.orbit.devotel.io/api/v1/cdp/audience/config/google \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "nango_connection_id": "conn_googleads_7d2e",
    "audience_id": "ul_91428",
    "segment_id": "seg_activated_trials",
    "schedule_minutes": 1440
  }'
```

Para su propio sink HTTPS en cambio, PATCH `/api/v1/cdp/audience/webhook` con `target_url` y un `signing_secret`; las entregas llegan firmadas `X-Orbit-Signature: t=<unix-sec>,v1=<hmac-sha256>`, el mismo esquema que su verificador de webhooks de Orbit ya comprueba. En cualquiera de los dos casos, los identificadores se hashean con SHA-256 antes del despacho a redes publicitarias — el PII en claro nunca sale del tenant.

Ejecute la primera activación explícitamente en lugar de esperar al calendario:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/cdp/audience/activate/google \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "seg_activated_trials",
    "operation": "add"
  }'
```

Haga primero un dry-run con `POST /api/v1/cdp/audience/preflight/google` siempre que el veredicto sea incierto — la misma puerta, nada se despacha. La puerta de pre-activación bloquea audiencias de tamaño insuficiente, cobertura baja de identificadores y violaciones de consentimiento o supresión; los ids de los controles fallados vuelven en la respuesta. Si esta organización tiene maker-checker activo, la ejecución se encola para la aprobación de una segunda persona — envíe, haga aprobar por un owner y reenvíe con el id de aprobación devuelto.

## 6. Lectura de confirmación y resolución de problemas

Confirme que la ejecución aterrizó y luego aprenda el presupuesto de latencia para distinguir lo sano de lo atascado.

**Confirmar.** `GET /api/v1/cdp/audience/activations` lista el historial de ejecuciones; `GET /api/v1/cdp/audience/activations/:id` profundiza en una ejecución con los recuentos `requested` / `matched` / `skipped` y los motivos de rechazo por miembro (nunca PII). Un estado `ok` con `matched` cercano a `requested` es sano; `partial` nombra su cubo; `skipped` significa que nada coincidió o que ninguna conexión se resolvió en el despacho. Para un destino warehouse en lugar de red publicitaria, lea los mismos veredictos en el [registro de ejecuciones de sincronización](https://docs.orbit.devotel.io/guides/cdp-sync-run-log.md) — por ejecución `attempted` / `delivered` / `rejected` / `failed` y las clases de error (`auth`, `validation`, `rate_limit`, …) que deciden el bucle de reintento.

**El presupuesto de latencia.** Cada fase tiene su propio retraso esperado; una queja solo se convierte en bug cuando una fase excede su presupuesto:

| Fase | Latencia esperada | Dónde comprobar |
| - | - | - |
| Evento → visible en ingest | segundos | Event debugger; una fila ausente en segundos significa rechazo de firma o del tracking plan. |
| Ingest → identidad cosida | minutos | La `contact_id` resuelta del evento en la fila del debugger; reglas de identidad que nunca coincidieron parecen eventos sin coser. |
| Cosido → membresía del segmento | un intervalo de auto-refresh | La membresía materializada del segmento; un `preview` manual muestra el recuento en vivo al instante, compare ambos. |
| Membresía → aterrizada en destino | un tick del calendario (los sweeps corren cada 15 minutos) | El historial de ejecuciones de activación o el registro de sincronización; `last_activation_status` en la configuración. |
| SLA de frescura del destino | 26 horas por destino | La bandera `overdue` del sync-run-log se activa más allá. |

Leer la tabla de arriba abajo convierte «la audiencia está mal» en «la fase N está fuera de presupuesto» en un solo pase. Reentre entonces en la guía dedicada de esa fase — fuente y destinos, reglas de identidad, segmentos, activación o reverse ETL — con el fallo ya localizado.

**Las cuatro formas de fallo que encontrará de verdad.** Un `409 CONNECTION_NOT_CONFIGURED` al activar significa que el destino no está del todo conectado (falta `audience_id` o el id de conexión). Un `422 AUDIENCE_PREFLIGHT_BLOCKED` nombra su control de puerta fallado — redimensione el segmento, arregle la cobertura de identificadores o anule deliberadamente. Cero miembros coincidentes significa que llegaron filas sin identificador fuerte — arregle el mapeo en el ingest, no en la activación. Una ejecución `partial` cuyo detalle muestra cubos `validation` con "missing or empty upsert identifier" significa que la clave de upsert no está mapeada — arregle el mapeo de campos y reejecute. Las cuatro están cubiertas por fase en las guías enlazadas arriba.

## Véase también

* [Consola de integración CDP: fuente y destinos](https://docs.orbit.devotel.io/guides/cdp-source-and-destinations.md) — profundización de fase 1: secretos, tipos de destino, circuit breakers
* [Firmado de ingest CDP](https://docs.orbit.devotel.io/guides/cdp-ingest-signing.md) — el contrato HMAC que implementan sus productores
* [Catálogo de datos CDP y reglas de identidad](https://docs.orbit.devotel.io/guides/cdp-data-catalog-and-identity-rules.md) — profundización de fase 2: formas de coincidencia, simulación, supervivencia
* [Audiencias CDP: construir segmentos](https://docs.orbit.devotel.io/guides/cdp-segments.md) — profundización de fase 3: el vocabulario completo de filtros, traits y puntuación
* [Pipelines de activación de audiencias](https://docs.orbit.devotel.io/guides/audience-activation-pipeline.md) — profundización de fase 4: cadencias, deltas, holdouts, resolución de problemas por plataforma
* [Reverse ETL CDP y exportaciones a warehouse](https://docs.orbit.devotel.io/guides/cdp-reverse-etl-and-warehouse-exports.md) — publique a un warehouse en vez de a una red publicitaria
* [Registro de ejecuciones de sincronización CDP](https://docs.orbit.devotel.io/guides/cdp-sync-run-log.md) — profundice las filas de sincronización a warehouse fallidas por clase de error


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.