Visão geral da API de Customer Journey

A API de Customer Journey permite que um backend gerencie Customer Journeys programaticamente: crie e edite definições de jornada, mova jornadas através de seu ciclo de vida (iniciar, pausar, finalizar, rascunho, arquivar), acione uma jornada em execução a partir de seus próprios sistemas e extraia estatísticas por jornada.

É a mesma API que o construtor de Customer Journey usa, exposta via REST/JSON através de uma ponte gRPC-Gateway.

URL Base

Os métodos gRPC-Gateway e os métodos externos legados são servidos em hosts diferentes:

Métodos	URL Base
gRPC-Gateway: `/api/v3/journeygateway/...` (ciclo de vida, criar, atualizar)	`https://journey-api.svc-nue.pushwoosh.com`
Legado externo: `/api/journey/...` (iniciar por API, estatísticas, remover usuários)	`https://journey.pushwoosh.com`

Autenticação

Cada solicitação deve incluir um cabeçalho Authorization com um token de acesso à API do lado do servidor da Pushwoosh:

Authorization: Api YOUR_API_TOKEN

Métodos

Gerenciar jornadas

Ciclo de vida: POST /api/v3/journeygateway/{action}. Inicie, pause, finalize, rascunhe ou arquive uma jornada por seu UUID.
Criar e atualizar: POST /api/v3/journeygateway e PUT /api/v3/journeygateway/{uuid}. Crie uma nova definição de jornada ou substitua uma existente.

Acionar jornadas

Iniciar por API: POST /api/journey/{id}/start/external. Injete usuários no ponto de entrada da API de uma jornada que já está em execução.

Estatísticas e público

Obter estatísticas da Jornada: GET /api/journey/{id}/statistics/external. Métricas de entrega e conversão por ponto.
Remover usuários de jornadas: POST /api/journey/drop-users/external. Remova usuários de todas ou de jornadas ativas selecionadas.

Referência

Objeto Journey: a forma da definição da jornada (info, params, points, comments) retornada pelos métodos de ciclo de vida, criação e atualização.
Referência de ponto: a estrutura point_data para cada tipo de ponto: elementos de entrada, tempo, divisão, ação e mensagens.

Início do ciclo de vida vs. Iniciar por API

A Customer Journey tem duas operações que parecem semelhantes, mas se comportam de maneira diferente.

O início do ciclo de vida altera o estado da jornada (por exemplo, de Rascunho para Em execução). Iniciar por API injeta usuários em uma jornada já em execução. A tabela abaixo os compara lado a lado.

	Início do Ciclo de Vida	Iniciar por API
Endpoint	`POST /api/v3/journeygateway/start`	`POST /api/journey/{id}/start/external`
O que faz	Ativa a jornada e a move para o estado Em execução	Injeta usuários no ponto de entrada da API de uma jornada já em execução
Estado da jornada necessário	Rascunho ou Pausada	Em execução (com um ponto de Início por API)
Frequência de execução	Uma vez por mudança de estado	Repetidamente, conforme os usuários precisam entrar

Formato de solicitação e resposta

Tipo de conteúdo: application/json.
Os nomes dos campos v3 usam snake_case. Os valores de Enum são serializados como seus nomes de string (por exemplo, "STATUS_RUNNING", "POINT_TYPE_SEND_PUSH").
Os métodos gRPC-Gateway (/api/v3/journeygateway/...) retornam o objeto journey em caso de sucesso e o envelope de erro padrão do gRPC-Gateway em caso de falha: { "code": ..., "message": ..., "details": [...] }.
Os métodos externos legados (/api/journey/...) retornam um corpo JSON específico do método em caso de sucesso e { "success": false, "message": ... } com HTTP 400 em erros de validação.

Início rápido

curl -X POST https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/start \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }'

Próximos passos

Ciclo de vida

Criar e atualizar

Iniciar por API

Obter estatísticas da Jornada

Remover usuários de jornadas

Objeto Journey

Referência de ponto