# Entrada baseada em API

<Aside type="caution" icon="setting" title="Necessária a ajuda do desenvolvedor">
 Você precisará da ajuda da sua equipe de desenvolvimento para configurar uma jornada de entrada baseada em API. Por favor, compartilhe este guia com eles.
</Aside>

## Como funciona

A entrada baseada em API permite que você inicie uma jornada do cliente no momento em que um evento de negócio específico ocorre. Para iniciar uma campanha, você precisa enviar uma requisição de API especial.

Aqui estão alguns casos de uso para uma entrada baseada em API:

*   Informar os clientes quando os produtos voltarem ao estoque
*   Avisar os usuários que o preço de um produto popular diminuiu
*   Notificar os assinantes quando um novo episódio de podcast for lançado

Diferente dos Eventos regulares, todos esses eventos de negócio podem ocorrer fora do aplicativo. Por exemplo, a disponibilidade de um produto só pode ser verificada em um banco de dados externo. É aqui que uma entrada baseada em API se torna útil: você pode configurar o envio de uma requisição para iniciar uma jornada sempre que certas mudanças ocorrerem fora do aplicativo (por exemplo, em seu banco de dados externo).

<img src="/shared-33.webp" alt="Elemento de entrada baseada em API na tela da jornada"/>

Funciona da seguinte forma:

1.  Crie uma jornada com uma entrada baseada em API. Nas configurações de entrada, você encontrará o modelo da requisição que inicia a jornada.
2.  Adicione condições de segmentação à requisição usando a [Linguagem de Segmentação](/pt/developer/api-reference/segmentation-filters-api/segmentation-language). Você também pode adicionar placeholders de conteúdo à requisição para alterar o conteúdo da mensagem dependendo do contexto.
3.  Automatize a requisição, se necessário. Por exemplo, informações sobre uma mudança de preço podem ser enviadas imediatamente do banco de dados para o webhook. Assim que isso acontecer, o webhook deve enviar automaticamente a requisição para iniciar a jornada. Você também pode enviar a requisição manualmente se não precisar de automação.

Você pode enviar a requisição um número ilimitado de vezes para alterar as condições de segmentação ou o conteúdo da mensagem.

Para mais detalhes, siga as instruções abaixo.

## Configurar uma jornada com entrada baseada em API

1.  Crie uma jornada com uma entrada baseada em API:

<video src="/journey-elements-api-based-entry-1.webm" title="Criar uma nova jornada e selecionar a entrada baseada em API" autoplay loop muted playsinline />

2.  Dê um duplo clique no passo de entrada baseada em API. A janela de configuração da entrada será aberta.

3.  Você pode modificar o conteúdo de push e e-mail toda vez que a jornada for iniciada usando placeholders de conteúdo. O valor de cada placeholder pode ser alterado na requisição. Se você não precisar desta opção, pode pular este passo.

> Por exemplo, você está criando uma jornada para notificar os assinantes quando um novo episódio de podcast é lançado. Usando um placeholder de conteúdo, você pode alterar o título do podcast toda vez que iniciar a jornada.

Primeiro, adicione os nomes dos placeholders na janela de configuração da entrada baseada em API. Você pode usar quaisquer nomes que sejam convenientes para você.

<img src="/journey-elements-api-based-entry-2.webp" alt="Adicionar nomes de placeholders de conteúdo na janela de configuração da entrada baseada em API"/>

Agora, crie uma [predefinição de push](/pt/product/content/push-presets) ou [conteúdo de e-mail](/pt/product/content/email-content/) e insira o placeholder no lugar do texto que você deseja modificar. O placeholder deve estar em um dos seguintes formatos, dependendo das suas necessidades:

*   `{placeholder_name|format_modifier|}` – se o valor do placeholder não for especificado ao iniciar a campanha, os usuários verão um espaço em branco em seu lugar.
*   `{placeholder_name|format_modifier}` – se o valor do placeholder não for especificado e ainda não tiver sido atribuído a um usuário (caso você tenha usado uma Tag como placeholder), a mensagem não será enviada.

<details>

<summary>Modificadores de formato</summary>

*   **CapitalizeFirst** – coloca em maiúscula a primeira letra do valor do placeholder
*   **CapitalizeAllFirst** – coloca em maiúscula as primeiras letras de todas as palavras no valor do placeholder
*   **UPPERCASE** – converte todas as letras para maiúsculas
*   **lowercase** – converte todas as letras para minúsculas
*   **regular** – insere o valor do placeholder exatamente como especificado na requisição

</details>

<img src="/journey-elements-api-based-entry-3.webp" alt="Inserir um placeholder em uma predefinição de push para conteúdo dinâmico"/>

<Aside type="tip">
Você também pode usar o nome de uma [Tag existente](/pt/product/audience-data-and-segmentation/user-data-tags/) em vez de um nome de placeholder. Neste caso, você deve configurar a substituição do valor desta Tag pelo valor especificado na requisição, conforme descrito abaixo.
</Aside>

Ao configurar o elemento de Push ou E-mail em sua jornada, selecione a predefinição criada e ative a opção **Personalizar mensagem com atributos do evento**.

Selecione os placeholders que você deseja modificar na requisição ao iniciar a jornada. Escolha a **Entrada baseada em API** como a fonte e o nome do placeholder como o atributo dinâmico:

<video src="/journey-elements-api-based-entry-4.webm" title="Personalizar mensagem com atributos de evento da entrada baseada em API" autoplay loop muted playsinline />

Clique em **Aplicar** para salvar as alterações.

4.  Na janela de configuração da entrada, copie o modelo de requisição para modificá-lo:

<img src="/journey-elements-api-based-entry-5.webp" alt="Copiar modelo de requisição da janela de configuração da entrada baseada em API"/>
<Aside> 
Para iniciar uma jornada via API, você deve incluir um token de autorização válido no cabeçalho de Autorização.

**Formato de cabeçalho obrigatório**

  ```http
  Authorization: Api <your_api_token>
  ```
  **Exemplo**

  ```http
  Authorization: Api c8dc6435-xxxxxxxxxxxxxxx
  ```
  
 </Aside>

5.  Adicione filtros de público ao parâmetro `"filter"` usando a [Linguagem de Segmentação](/pt/developer/api-reference/segmentation-filters-api/segmentation-language) ou [copie a lógica de segmentação](/pt/product/audience-data-and-segmentation/segmentation/#copy-segment-logic) dos seus segmentos. Configure as [Tags](/pt/product/audience-data-and-segmentation/user-data-tags/tags) necessárias com antecedência.

Por exemplo, para segmentar usuários que adicionaram o item _Socks_ à sua _Wishlist_, o valor de `"filter"` deve ser o seguinte:

`"filter": "A(\"12345-12345\") * "T(\"Wishlist\", EQ, \"Socks\")"`

Neste exemplo, você deve ter uma Tag _Wishlist_ configurada em seu aplicativo.

<Aside type="note">
O código da sua aplicação é adicionado automaticamente ao parâmetro `"filter"` no formato `A(\"12345-12345\")`. Não o remova ou modifique.

Além disso, lembre-se de que aspas ("") e barras invertidas (\\) devem ser escapadas com uma barra invertida (\\) em consultas JSON.
</Aside>

<Aside type="tip">
Você também pode segmentar dispositivos ou usuários específicos diretamente, passando um array de HWIDs no parâmetro `"hwids"` ou IDs de Usuário no parâmetro `"users"`, em vez de usar filtros:

```json
"users": ["user_id_1", "user_id_2", ...],
"hwids": ["hwid_1", "hwid_2", ...]
```
</Aside>

6.  Se você configurou placeholders, especifique o conteúdo desejado como seus valores:

<img src="/journey-elements-api-based-entry-6.webp" alt="Especificar valores de placeholder na requisição de API para iniciar a jornada"/>

7.  Se você planeja reiniciar sua campanha com frequência e não quer que os mesmos usuários entrem na jornada várias vezes, defina [Limites de entrada na campanha](/pt/product/customer-journey/journey-settings#campaign-entry-limit).

> Por exemplo, você criou uma campanha para notificar os usuários sobre a redução de preço de um produto específico. Você quer reiniciar a jornada algumas vezes, enviando várias requisições com diferentes filtros de público. Neste caso, você pode adicionar limites de entrada na campanha para que a notificação não seja enviada repetidamente para usuários que correspondam a múltiplos filtros.

8.  Se você quer que uma jornada seja iniciada sempre que um determinado evento de negócio acontecer, automatize a requisição usando o webhook. Assim que o evento ocorrer, o webhook deve enviar automaticamente a requisição para iniciar a jornada.

Você também pode enviar a requisição manualmente se não precisar de automação.

<Aside type="note">
*   Se você alterar as condições de segmentação ao enviar uma nova requisição, isso não afetará os usuários que já entraram na jornada.
*   Se você alterar o conteúdo da mensagem ao enviar uma nova requisição, todos os usuários receberão a nova versão da mensagem (incluindo aqueles que já entraram na jornada, mas ainda não receberam esta mensagem).
</Aside>