# Visão geral da API de Customer Journey

A API de Customer Journey permite que um backend gerencie [Customer Journeys](/pt/product/customer-journey/pushwoosh-journey-overview/) de forma programática: crie e edite definições de jornadas, 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 sobre REST/JSON através de uma ponte gRPC-Gateway.

## URL Base

```
https://journey.pushwoosh.com
```

<Aside type="tip">
Se você usa uma região dedicada ou uma implantação privada, confirme a URL base exata com seu Gerente de Sucesso do Cliente Pushwoosh.
</Aside>

## Autenticação

Cada solicitação deve incluir um cabeçalho `Authorization` com um [token de acesso à API](/pt/developer/api-reference/api-access-token/#server-api-token) do lado do servidor da Pushwoosh:

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="note">
O token está vinculado à conta que o possui. Todas as operações se aplicam a essa conta. Use o mesmo token que você emite para outras chamadas de API de servidor para servidor e nunca o exponha em aplicativos cliente.
</Aside>

## Métodos

### Gerenciar jornadas

- [Ciclo de vida](/pt/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. Inicie, pause, finalize, rascunhe ou arquive uma jornada por seu UUID.
- [Criar e atualizar](/pt/developer/api-reference/customer-journey-api/create-update/): `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](/pt/developer/api-reference/customer-journey-api/start-by-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](/pt/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. Métricas de entrega e conversão por ponto.
- [Remover usuários de jornadas](/pt/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. Remova usuários de todas ou de jornadas ativas selecionadas.

### Referência

- [Objeto Journey](/pt/developer/api-reference/customer-journey-api/journey-object/): 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](/pt/developer/api-reference/customer-journey-api/point-reference/): 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.

[Início do ciclo de vida](/pt/developer/api-reference/customer-journey-api/lifecycle/#endpoints) altera o estado da jornada (por exemplo, de Rascunho para **Em execução**).
[Iniciar por API](/pt/developer/api-reference/customer-journey-api/start-by-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 Pausado | Em execução (com um ponto de Início de 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 enumeração 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](/pt/developer/api-reference/customer-journey-api/journey-object/) 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

```bash title="Iniciar uma jornada"
curl -X POST https://journey.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

<CardGrid>
  <LinkCard title="Ciclo de vida" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Criar e atualizar" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Iniciar por API" href="/developer/api-reference/customer-journey-api/start-by-api/" />
  <LinkCard title="Obter estatísticas da Jornada" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Remover usuários de jornadas" href="/developer/api-reference/customer-journey-api/drop-users/" />
  <LinkCard title="Objeto Journey" href="/developer/api-reference/customer-journey-api/journey-object/" />
  <LinkCard title="Referência de ponto" href="/developer/api-reference/customer-journey-api/point-reference/" />
</CardGrid>