# Objeto Journey

Los métodos [lifecycle](/es/developer/api-reference/customer-journey-api/lifecycle/), [create y update](/es/developer/api-reference/customer-journey-api/create-update/) devuelven un objeto Journey con la misma estructura de nivel superior:

```json title="Estructura"
{
  "info": { ... },        // metadatos de solo lectura (solo respuestas)
  "params": { ... },      // configuración para todo el Journey (crear/actualizar)
  "points": [ ... ],      // nodos del lienzo y sus conexiones
  "comments": [ ... ]     // comentarios del lienzo
}
```

Cuando usted **crea** o **actualiza** un Journey, envía `title`, `params`, `points` y `comments`. Las respuestas devuelven `info` (que contiene `params`) además de `points` y `comments`.

## Info

Metadatos del Journey de solo lectura. Devueltos por cada método v3. No forma parte del cuerpo de la solicitud.

| Campo | Tipo | Descripción |
|---|---|---|
| `uuid` | string | [ID del Journey](/es/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | Nombre del Journey. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | Estado actual. |
| `created_at` | string | Marca de tiempo de creación (ISO 8601). |
| `updated_at` | string | Marca de tiempo de la última actualización (ISO 8601). |
| `is_first_activated` | bool | Si el Journey se ha iniciado al menos una vez. |
| `params` | [`JourneyParams`](#journeyparams) | Configuración para todo el Journey. |
| `category_uuid` | string | UUID de la categoría, o vacío si no está categorizado. |
| `pointCounts` | map<string, uint32> | Recuento de puntos por tipo. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | Cómo entran los usuarios al Journey. |
| `stop_reason` | string | Por qué se detuvo el Journey, si aplica. |
| `last_edited_by` | `User` | Usuario que editó por última vez el Journey. |
| `dynamic_entry` | bool | Si la entrada dinámica está habilitada. |

## JourneyParams

Configuración para todo el Journey. Se envía al crear/actualizar y se devuelve dentro de `info.params`.

| Campo | Tipo | Descripción |
|---|---|---|
| `application_code` | string | [Código de aplicación](/es/developer/api-reference/api-identifiers/#application-code) al que pertenece el Journey. Requerido al crear. |
| `silent_hours` | [`SilentHours`](#silenthours) | Horas durante las cuales se suprimen los mensajes, por canal. |
| `capping` | [`EntryCapping`](#entrycapping) | Límites sobre la frecuencia con la que un usuario puede volver a entrar en el Journey. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | Ventana para atribuir conversiones de objetivos. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | Cómo manejar el cambio de ID de un usuario a mitad del Journey. |

### SilentHours

Suprime el envío durante las horas de silencio. Configurado **por canal**: cada canal toma sus propios `SilentHoursParams`:

| Campo | Tipo | Descripción |
|---|---|---|
| `push_params` | `SilentHoursParams` | Horas de silencio para notificaciones push. |
| `inapp_params` | `SilentHoursParams` | Horas de silencio para mensajes in-app. |
| `email_params` | `SilentHoursParams` | Horas de silencio para correos electrónicos. |
| `sms_params` | `SilentHoursParams` | Horas de silencio para SMS. |
| `whatsapp_params` | `SilentHoursParams` | Horas de silencio para WhatsApp. |
| `line_params` | `SilentHoursParams` | Horas de silencio para LINE. |

Cada `SilentHoursParams` es:

| Campo | Tipo | Descripción |
|---|---|---|
| `enabled` | bool | Si las horas de silencio se aplican a este canal. |
| `from_time` | `Time` | Inicio de la ventana de silencio: `{ "hour": 0–23, "minute": 0–59 }`. |
| `to_time` | `Time` | Fin de la ventana de silencio. |
| `week_days` | bool[] | Siete booleanos para los días en que se aplica la ventana (Lunes = índice 0). |
| `behavior` | enum | Qué hacer cuando un mensaje cae dentro de las horas de silencio: `WaitAndSend` (retener, luego enviar cuando termine la ventana), `DropAndGo` (omitir el mensaje, continuar el Journey inmediatamente), o `WaitAndDrop` (esperar a que termine la ventana, luego continuar sin enviar). |

### EntryCapping

Limita la frecuencia con la que el mismo usuario puede entrar en el Journey.

| Campo | Tipo | Descripción |
|---|---|---|
| `is_enabled` | bool | Si el límite de entrada está activado. |
| `period` | uint64 | Número mínimo de segundos entre las entradas de un usuario. |

### ConversionWindow

| Campo | Tipo | Descripción |
|---|---|---|
| `seconds` | uint64 | Cuánto tiempo después de entrar en un Journey la finalización de un objetivo por parte de un usuario todavía cuenta como una conversión. |

## Punto

Un punto es un nodo en el lienzo del Journey: un punto de entrada, un mensaje, un retraso, un divisor, etc.

| Campo | Tipo | Descripción |
|---|---|---|
| `uuid` | string | ID único del punto dentro del Journey. Debe ser un UUID canónico [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122): 32 dígitos hexadecimales en grupos 8-4-4-4-12. |
| `title` | string | Nombre de visualización del punto. |
| `point_type` | [`PointType`](#pointtype-enum) | El tipo de nodo. |
| `outputs` | array de [`PointOutput`](#pointoutput) | Conexiones a puntos posteriores. |
| `position` | [`Position`](#position) | Coordenadas del lienzo. |
| `point_data` | object | Exactamente una clave anidada, que coincide con `point_type` (consulte la tabla de [tipos de punto](#tipos-de-punto-y-point_data)). |

<Aside type="note">
Todos los UUID (`info.uuid`, cada `uuid` de punto y el `next_point_uuid` de cada salida) deben ser UUID canónicos RFC 4122 (grupos hexadecimales 8-4-4-4-12).
</Aside>

### PointOutput

Las salidas de un punto son sus ramas salientes. Sus claves **no son de formato libre**. El validador espera un conjunto exacto de claves para cada tipo de punto, y rechaza un Journey cuyo punto tenga un número incorrecto de salidas o una clave que no reconoce.

| Campo | Tipo | Descripción |
|---|---|---|
| `identity.key` | string | Clave de la rama. Debe seguir las [reglas de claves de salida](#claves-de-salida) a continuación. |
| `identity.order` | int | Orden de visualización de la rama. |
| `info.title` | string | Etiqueta de rama opcional. |
| `info.next_point_uuid` | string | UUID del siguiente punto al que se conecta esta rama. |

#### Claves de salida

La rama predeterminada (la primera) siempre se llama `"default"`. Las ramas adicionales se nombran `"output1"`, `"output2"`, ... (el prefijo `output` seguido de un índice basado en 1). Dos tipos de punto rompen esta regla, como se indica a continuación.

| Tipo de punto | Claves de salida esperadas |
|---|---|
| Puntos de entrada (`START_BY_SEGMENT`, `START_BY_API`, `EVENT`), `INAPP`, `SET_TAGS`, `WEBHOOK`, `AUDIENCE_SYNC`, y puntos de mensaje sin divisor (`SEND_PUSH`, `SEND_EMAIL`, `SEND_SMS`, `SEND_WHATSAPP`, `SEND_LINE`, `SEND_KAKAO`, `SEND_TELEGRAM`, `SEND_DATA`) | `default` |
| `GOAL_EVENT`, `EXIT` | ninguna (sin salidas) |
| `FILTER` | `default`, `output1` |
| `BOOLEAN_SPLITTER` | `default`, luego `output1` ... `outputN` (una rama extra por condición. Una división simple de sí/no es `default` + `output1`) |
| `WAIT` (retraso) | `default`. Un retraso dinámico con división de ramas añade `output1` |
| `WAIT_EVENT` | `default` es la rama de **evento no activado**. `output1` (o, con un script de condiciones, una rama por condición) es la ruta activada |
| `SEND_PUSH` con un divisor | `default`, `output1` (y `output2` cuando tanto el divisor de mensaje como el de entrega están activados) |
| `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` con un divisor | `default`, `output1` |
| `SEND_WHATSAPP` con un preset de respuesta rápida | `default`, más una rama por respuesta rápida. La clave es el valor de la respuesta rápida en sí |
| `AB_SPLITTER` | `output0`, `output1`, `output2`, ... (una por variante. **No hay rama `default`**) |

### Position

| Campo | Tipo | Descripción |
|---|---|---|
| `x` | float | Coordenada horizontal en el lienzo. |
| `y` | float | Coordenada vertical en el lienzo. |

## Tipos de punto y point_data

`point_data` es un "one-of": contiene exactamente un objeto anidado cuya clave está determinada por el `point_type` del punto.

| `point_type` | clave `point_data` | Propósito |
|---|---|---|
| `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | Entrada: usuarios que coinciden con un segmento. |
| `POINT_TYPE_EVENT` | `message_bus` | Entrada: usuarios que activan un evento. |
| `POINT_TYPE_START_BY_API` | `start_by_api` | Entrada: usuarios inyectados a través de la llamada [Start by API](/es/developer/api-reference/customer-journey-api/start-by-api/). |
| `POINT_TYPE_WAIT` | `delay` | Esperar un intervalo fijo o dinámico. |
| `POINT_TYPE_WAIT_EVENT` | `wait_event` | Esperar hasta que ocurra un evento. |
| `POINT_TYPE_SEND_PUSH` | `send_push` | Enviar una notificación push. |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | Enviar un correo electrónico. |
| `POINT_TYPE_SEND_SMS` | `send_sms` | Enviar un SMS. |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | Enviar un mensaje de WhatsApp. |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Enviar un mensaje de Telegram. |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | Enviar un mensaje de Kakao. |
| `POINT_TYPE_SEND_LINE` | `send_line` | Enviar un mensaje de LINE. |
| `POINT_TYPE_SEND_DATA` | `send_data` | Enviar un mensaje de datos silencioso. |
| `POINT_TYPE_INAPP` | `inapp` | Mostrar un mensaje in-app. |
| `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | Dividir usuarios por una condición (segmento, tags o evento). |
| `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | Dividir usuarios en grupos A/B. |
| `POINT_TYPE_FILTER` | `filter` | Permitir que solo los usuarios que coincidan con un filtro continúen. |
| `POINT_TYPE_SET_TAGS` | `set_tags` | Actualizar los tags de usuario. |
| `POINT_TYPE_WEBHOOK` | `web_hook` | Enviar una solicitud HTTP saliente. |
| `POINT_TYPE_GOAL_EVENT` | `goal_event` | Rastrear un objetivo de conversión. |
| `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | Sincronizar usuarios con una audiencia externa. |
| `POINT_TYPE_EXIT` | `terminator` | Salir del Journey. |

<Aside type="note">
Las cargas útiles de `point_data` por tipo están documentadas en la [Referencia de puntos](/es/developer/api-reference/customer-journey-api/point-reference/). Los puntos de entrada, temporización, división y acción se cubren en su totalidad allí. Los puntos de mensajería se cubren a nivel de envoltura con enlaces a los documentos del canal correspondiente.
</Aside>

### Punto de ejemplo

Un punto "set tags" con una única conexión descendente:

```json
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}
```

## JourneyComment

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | UUID del comentario. |
| `message` | string | Texto del comentario. |
| `position` | [`Position`](#position) | Coordenadas del lienzo. |
| `index` | int | Orden de visualización. |
| `created_at` | string | Marca de tiempo de creación (ISO 8601). |
| `deleted` | bool | Si el comentario está eliminado. |

## Enums

### JourneyStatus enum

`STATUS_DRAFT`, `STATUS_RUNNING`, `STATUS_FINISHED`, `STATUS_ARCHIVED`, `STATUS_PAUSED`, `STATUS_UNKNOWN`.

### CampaignType enum

- `TriggerBased`: los usuarios entran por un evento.
- `AudienceBased`: los usuarios entran desde un segmento.
- `APIBased`: los usuarios entran a través de la llamada Start by API.
- `Mixed`: más de un tipo de entrada.
- `Unknown`: tipo de entrada no determinado.

### PointType enum

Consulte la tabla de [tipos de punto](#tipos-de-punto-y-point_data) anterior para ver la lista completa y la clave `point_data` a la que se asigna cada uno.

### UserIDTrackChangePolicy enum

Controla lo que le sucede a un usuario que está a mitad de un Journey cuando su [ID de Usuario](/es/developer/api-reference/api-identifiers/#user-id) cambia:

- `DEFAULT`: comportamiento predeterminado.
- `TRACK`: seguir rastreando al usuario bajo el nuevo ID.
- `DROP`: eliminar al usuario del Journey cuando su ID cambia.

## Relacionado

<CardGrid>
  <LinkCard title="Referencia de puntos" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="Crear y actualizar" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Ciclo de vida" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>