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.

Dica

Não confunda esta chamada com o Início do ciclo de vida, 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.

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.

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.

Parâmetros de caminho

Nome	Tipo	Descrição
id	string	ID da Journey 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.

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 para entrar. Mutuamente exclusivo com hwids e filter.
payload.hwids	string[]	HWIDs para entrar. Mutuamente exclusivo com users e filter.
payload.filter	string	Uma expressão seglang selecionando o público. Mutuamente exclusivo com users e hwids.
payload.attribute_values	map<string, string>	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

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

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

Inserir um público por filtro

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

Resposta

200

{
  "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.

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).

Relacionados

Ciclo de vida

Obter estatísticas da Journey

Linguagem de segmentação