# Objeto Journey

Os métodos de [ciclo de vida](/pt/developer/api-reference/customer-journey-api/lifecycle/), [criação e atualização](/pt/developer/api-reference/customer-journey-api/create-update/) todos retornam um objeto de jornada com a mesma estrutura de nível superior:

```json title="Estrutura"
{
  "info": { ... },        // metadados somente leitura (apenas respostas)
  "params": { ... },      // configuração de toda a jornada (criar / atualizar)
  "points": [ ... ],      // nós da tela e suas conexões
  "comments": [ ... ]     // comentários da tela
}
```

Quando você **cria** ou **atualiza** uma jornada, você envia `title`, `params`, `points` e `comments`. As respostas retornam `info` (que contém `params`), além de `points` e `comments`.

## Info

Metadados da jornada somente leitura. Retornado por todos os métodos v3. Não faz parte do corpo da solicitação.

| Campo | Tipo | Descrição |
|---|---|---|
| `uuid` | string | [ID da Journey](/pt/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | Nome da jornada. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | Estado atual. |
| `created_at` | string | Timestamp de criação (ISO 8601). |
| `updated_at` | string | Timestamp da última atualização (ISO 8601). |
| `is_first_activated` | bool | Se a jornada foi iniciada pelo menos uma vez. |
| `params` | [`JourneyParams`](#journeyparams) | Configuração de toda a jornada. |
| `category_uuid` | string | UUID da categoria, ou vazio se não categorizado. |
| `pointCounts` | map<string, uint32> | Contagem de pontos por tipo. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | Como os usuários entram na jornada. |
| `stop_reason` | string | Por que a jornada parou, se aplicável. |
| `last_edited_by` | `User` | Usuário que editou a jornada pela última vez. |
| `dynamic_entry` | bool | Se a entrada dinâmica está habilitada. |

## JourneyParams

Configuração de toda a jornada. Enviado na criação/atualização e retornado dentro de `info.params`.

| Campo | Tipo | Descrição |
|---|---|---|
| `application_code` | string | [Código do aplicativo](/pt/developer/api-reference/api-identifiers/#application-code) ao qual a jornada pertence. Obrigatório na criação. |
| `silent_hours` | [`SilentHours`](#silenthours) | Horas durante as quais as mensagens são suprimidas, por canal. |
| `capping` | [`EntryCapping`](#entrycapping) | Limites de frequência com que um usuário pode reentrar na jornada. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | Janela para atribuir conversões de meta. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | Como lidar com a mudança de ID de um usuário no meio da jornada. |

### SilentHours

Suprime o envio durante as horas de silêncio. Configurado **por canal**: cada canal utiliza seus próprios `SilentHoursParams`:

| Campo | Tipo | Descrição |
|---|---|---|
| `push_params` | `SilentHoursParams` | Horas de silêncio para notificações push. |
| `inapp_params` | `SilentHoursParams` | Horas de silêncio para mensagens in-app. |
| `email_params` | `SilentHoursParams` | Horas de silêncio para e-mails. |
| `sms_params` | `SilentHoursParams` | Horas de silêncio para SMS. |
| `whatsapp_params` | `SilentHoursParams` | Horas de silêncio para WhatsApp. |
| `line_params` | `SilentHoursParams` | Horas de silêncio para LINE. |

Cada `SilentHoursParams` é:

| Campo | Tipo | Descrição |
|---|---|---|
| `enabled` | bool | Se as horas de silêncio se aplicam a este canal. |
| `from_time` | `Time` | Início da janela de silêncio: `{ "hour": 0–23, "minute": 0–59 }`. |
| `to_time` | `Time` | Fim da janela de silêncio. |
| `week_days` | bool[] | Sete booleanos para os dias em que a janela se aplica (Segunda-feira = índice 0). |
| `behavior` | enum | O que fazer quando uma mensagem cai dentro das horas de silêncio: `WaitAndSend` (reter e enviar quando a janela terminar), `DropAndGo` (pular a mensagem, continuar a jornada imediatamente), ou `WaitAndDrop` (esperar o fim da janela e continuar sem enviar). |

### EntryCapping

Limita a frequência com que o mesmo usuário pode entrar na jornada.

| Campo | Tipo | Descrição |
|---|---|---|
| `is_enabled` | bool | Se o limite de entrada está ativado. |
| `period` | uint64 | Número mínimo de segundos entre as entradas de um usuário. |

### ConversionWindow

| Campo | Tipo | Descrição |
|---|---|---|
| `seconds` | uint64 | Quanto tempo após entrar em uma jornada a conclusão de uma meta pelo usuário ainda conta como uma conversão. |

## Point

Um ponto é um nó na tela da jornada: um ponto de entrada, uma mensagem, um atraso, um divisor, e assim por diante.

| Campo | Tipo | Descrição |
|---|---|---|
| `uuid` | string | ID único do ponto dentro da jornada. Deve ser um UUID canônico [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122): 32 dígitos hexadecimais em grupos de 8-4-4-4-12. |
| `title` | string | Nome de exibição do ponto. |
| `point_type` | [`PointType`](#pointtype-enum) | O tipo de nó. |
| `outputs` | array of [`PointOutput`](#pointoutput) | Conexões com pontos subsequentes. |
| `position` | [`Position`](#position) | Coordenadas na tela. |
| `point_data` | object | Exatamente uma chave aninhada, correspondendo a `point_type` (veja a tabela de [tipos de ponto](#point-types-and-point_data)). |

<Aside type="note">
Todos os UUIDs (`info.uuid`, cada `uuid` de ponto, e o `next_point_uuid` de cada saída) devem ser UUIDs canônicos RFC 4122 (grupos hexadecimais 8-4-4-4-12).
</Aside>

### PointOutput

As saídas de um ponto são suas ramificações de saída. Suas chaves **não são de formato livre**. O validador espera um conjunto exato de chaves para cada tipo de ponto e rejeita uma jornada cujo ponto tenha o número errado de saídas ou uma chave que não reconhece.

| Campo | Tipo | Descrição |
|---|---|---|
| `identity.key` | string | Chave da ramificação. Deve seguir as [regras de chaves de saída](#output-keys) abaixo. |
| `identity.order` | int | Ordem de exibição da ramificação. |
| `info.title` | string | Rótulo opcional da ramificação. |
| `info.next_point_uuid` | string | UUID do próximo ponto ao qual esta ramificação se conecta. |

#### Chaves de saída

A ramificação padrão (primeira) é sempre chamada de `"default"`. Ramificações adicionais são chamadas de `"output1"`, `"output2"`, ... (o prefixo `output` seguido por um índice baseado em 1). Dois tipos de ponto quebram essa regra, conforme observado abaixo.

| Tipo de ponto | Chaves de saída esperadas |
|---|---|
| Pontos de entrada (`START_BY_SEGMENT`, `START_BY_API`, `EVENT`), `INAPP`, `SET_TAGS`, `WEBHOOK`, `AUDIENCE_SYNC`, e pontos de mensagem sem divisor (`SEND_PUSH`, `SEND_EMAIL`, `SEND_SMS`, `SEND_WHATSAPP`, `SEND_LINE`, `SEND_KAKAO`, `SEND_TELEGRAM`, `SEND_DATA`) | `default` |
| `GOAL_EVENT`, `EXIT` | nenhuma (sem saídas) |
| `FILTER` | `default`, `output1` |
| `BOOLEAN_SPLITTER` | `default`, depois `output1` … `outputN` (uma ramificação extra por condição. Uma divisão simples de sim/não é `default` + `output1`) |
| `WAIT` (atraso) | `default`. Um atraso dinâmico com divisão de ramificação adiciona `output1` |
| `WAIT_EVENT` | `default` é a ramificação de **evento não acionado**. `output1` (ou, com um script de condições, uma ramificação por condição) é o caminho acionado |
| `SEND_PUSH` com um divisor | `default`, `output1` (e `output2` quando os divisores de mensagem e de entrega estão ambos ativados) |
| `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` com um divisor | `default`, `output1` |
| `SEND_WHATSAPP` com um preset de resposta rápida | `default`, mais uma ramificação por resposta rápida. A chave é o próprio valor da resposta rápida |
| `AB_SPLITTER` | `output0`, `output1`, `output2`, … (um por variante. **Não há ramificação `default`**) |

### Position

| Campo | Tipo | Descrição |
|---|---|---|
| `x` | float | Coordenada horizontal na tela. |
| `y` | float | Coordenada vertical na tela. |

## Tipos de ponto e point_data

`point_data` é um one-of: ele carrega exatamente um objeto aninhado cuja chave é determinada pelo `point_type` do ponto.

| `point_type` | chave `point_data` | Propósito |
|---|---|---|
| `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | Entrada: usuários que correspondem a um segmento. |
| `POINT_TYPE_EVENT` | `message_bus` | Entrada: usuários que acionam um evento. |
| `POINT_TYPE_START_BY_API` | `start_by_api` | Entrada: usuários injetados através da chamada [Start by API](/pt/developer/api-reference/customer-journey-api/start-by-api/). |
| `POINT_TYPE_WAIT` | `delay` | Aguardar por um intervalo fixo ou dinâmico. |
| `POINT_TYPE_WAIT_EVENT` | `wait_event` | Aguardar até que um evento ocorra. |
| `POINT_TYPE_SEND_PUSH` | `send_push` | Enviar uma notificação push. |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | Enviar um e-mail. |
| `POINT_TYPE_SEND_SMS` | `send_sms` | Enviar um SMS. |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | Enviar uma mensagem de WhatsApp. |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Enviar uma mensagem de Telegram. |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | Enviar uma mensagem de Kakao. |
| `POINT_TYPE_SEND_LINE` | `send_line` | Enviar uma mensagem de LINE. |
| `POINT_TYPE_SEND_DATA` | `send_data` | Enviar uma mensagem de dados silenciosa. |
| `POINT_TYPE_INAPP` | `inapp` | Mostrar uma mensagem in-app. |
| `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | Dividir usuários por uma condição (segmento, tags ou evento). |
| `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | Dividir usuários em grupos A/B. |
| `POINT_TYPE_FILTER` | `filter` | Permitir que apenas usuários que correspondem a um filtro continuem. |
| `POINT_TYPE_SET_TAGS` | `set_tags` | Atualizar tags de usuário. |
| `POINT_TYPE_WEBHOOK` | `web_hook` | Enviar uma solicitação HTTP de saída. |
| `POINT_TYPE_GOAL_EVENT` | `goal_event` | Rastrear uma meta de conversão. |
| `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | Sincronizar usuários com uma audiência externa. |
| `POINT_TYPE_EXIT` | `terminator` | Sair da jornada. |

<Aside type="note">
Os payloads `point_data` por tipo estão documentados na [Referência de Ponto](/pt/developer/api-reference/customer-journey-api/point-reference/). Pontos de entrada, tempo, divisão e ação são abordados em detalhes lá. Os pontos de mensagens são abordados no nível do envelope com links para a documentação do canal relevante.
</Aside>

### Ponto de exemplo

Um ponto "definir tags" com uma única conexão subsequente:

```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 | Descrição |
|---|---|---|
| `id` | string | UUID do comentário. |
| `message` | string | Texto do comentário. |
| `position` | [`Position`](#position) | Coordenadas na tela. |
| `index` | int | Ordem de exibição. |
| `created_at` | string | Timestamp de criação (ISO 8601). |
| `deleted` | bool | Se o comentário foi excluído. |

## Enums

### Enum JourneyStatus

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

### Enum CampaignType

- `TriggerBased`: usuários entram em um evento.
- `AudienceBased`: usuários entram a partir de um segmento.
- `APIBased`: usuários entram através da chamada Start by API.
- `Mixed`: mais de um tipo de entrada.
- `Unknown`: tipo de entrada não determinado.

### Enum PointType

Veja a tabela de [tipos de ponto](#point-types-and-point_data) acima para a lista completa e a chave `point_data` à qual cada um corresponde.

### Enum UserIDTrackChangePolicy

Controla o que acontece com um usuário que está no meio da jornada quando seu [ID de Usuário](/pt/developer/api-reference/api-identifiers/#user-id) muda:

- `DEFAULT`: comportamento padrão.
- `TRACK`: continuar rastreando o usuário sob o novo ID.
- `DROP`: remover o usuário da jornada quando seu ID mudar.

## Relacionados

<CardGrid>
  <LinkCard title="Referência de ponto" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="Criar e atualizar" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Ciclo de vida" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>