# Iniciar por API

`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`

Insere um conjunto de usuários no **ponto de entrada da API** de uma journey. Use-o para impulsionar journeys a partir do seu próprio backend. Por exemplo, inicie um fluxo de onboarding quando um usuário concluir o cadastro no seu servidor.

<Aside type="tip">
Não confunda esta chamada com o [Início do ciclo de vida](/pt/developer/api-reference/customer-journey-api/lifecycle/#endpoints), que ativa uma journey e a move para o estado **Em Execução**. O Iniciar por API injeta usuários em uma journey que já está em execução. Consulte a [tabela de comparação](/pt/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## Pré-requisitos

- A journey está no estado **Em Execução**.
- A journey contém exatamente um ponto de entrada da API (o elemento "Iniciar por API"), e esse elemento não está desativado.
- Os nomes dos atributos que você envia correspondem aos atributos configurados nesse ponto de entrada da API.

<Aside type="caution" title="Limite de taxa">
Cada ponto de entrada da API aceita **uma requisição por minuto**. Uma segunda requisição dentro dessa janela retorna um erro (`Enhance your calm! only one request per minute is allowed`). Agrupe seus destinatários em uma única requisição em vez de enviar várias pequenas.
</Aside>

## Parâmetros de caminho

| Nome | Tipo | Descrição |
|---|---|---|
| `id` | string | [ID da Journey](/pt/developer/api-reference/api-identifiers/#journey-id) da journey em execução. |

## Cabeçalhos da requisição

| Nome | Obrigatório | Valor |
|---|---|---|
| `Content-Type` | Sim | `application/json` |
| `Authorization` | Sim | `Api <server_api_token>`. Consulte [Token de API do servidor](/pt/developer/api-reference/api-access-token/#server-api-token). |

## Corpo da requisição

O corpo tem um único objeto `payload`. Você deve fornecer **exatamente um** dos seguintes: `users`, `hwids` ou `filter` para selecionar quem entra na journey.

| Campo | Tipo | Descrição |
|---|---|---|
| `payload.users` | string[] | [IDs de Usuário](/pt/developer/api-reference/api-identifiers/#user-id) para entrar. Mutuamente exclusivo com `hwids` e `filter`. |
| `payload.hwids` | string[] | [HWIDs](/pt/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) para entrar. Mutuamente exclusivo com `users` e `filter`. |
| `payload.filter` | string | Uma expressão [seglang](/pt/developer/api-reference/segmentation-filters-api/segmentation-language/) selecionando o público. Mutuamente exclusivo com `users` e `hwids`. |
| `payload.attribute_values` | map&lt;string, string&gt; | Opcional. Valores para os atributos personalizados definidos no ponto de entrada da API. Cada chave deve corresponder a um nome de atributo configurado. |

### Exemplos de requisição

##### Inserir usuários específicos

```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'
```
##### Inserir usuários específicos com atributos

```json
{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}
```

##### Inserir um público por filtro

```json
{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}
```


## Resposta

<Tabs>
<TabItem label="200">

```json
{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `request_uuid` | string | Identificador da requisição de entrada aceita. A requisição é processada de forma assíncrona. |

</TabItem>
<TabItem label="400">

Erros de validação retornam HTTP `400` com uma mensagem descritiva. Casos comuns:

| Mensagem | Causa |
|---|---|
| `one of users, hwids or filter must be provided` | Nenhum dos três seletores foi definido. |
| `only one of users, hwids or filter must be provided` | Mais de um seletor foi definido. |
| `Journey is not running` | A journey não está no estado Em Execução. |
| `zero api start points` | A journey não tem ponto de entrada da API. |
| `there is more then one api start point` | A journey tem mais de um ponto de entrada da API. |
| `point is deactivated` | O ponto de entrada da API está desativado. |
| `unknown attribute: <name>` | Uma chave `attribute_values` não está configurada no ponto de entrada da API. |
| `Enhance your calm! only one request per minute is allowed` | Limite de taxa atingido (uma requisição por minuto por ponto de entrada). |

</TabItem>
</Tabs>

## Relacionados

<CardGrid>
  <LinkCard title="Ciclo de vida" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Obter estatísticas da Journey" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Linguagem de segmentação" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>