# Übersicht über die Customer Journey API

Die Customer Journey API ermöglicht es einem Backend, [Customer Journeys](/de/product/customer-journey/pushwoosh-journey-overview/) programmgesteuert zu verwalten: Journey-Definitionen erstellen und bearbeiten, Journeys durch ihren Lebenszyklus bewegen (starten, pausieren, beenden, entwerfen, archivieren), eine laufende Journey von Ihren eigenen Systemen aus auslösen und Statistiken pro Journey abrufen.

Es ist dieselbe API, die der Customer Journey Builder verwendet, und sie wird über REST/JSON durch eine gRPC-Gateway-Bridge bereitgestellt.

## Basis-URL

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

<Aside type="tip">
Wenn Sie eine dedizierte Region oder eine private Bereitstellung verwenden, bestätigen Sie die genaue Basis-URL bei Ihrem Pushwoosh Customer Success Manager.
</Aside>

## Authentifizierung

Jede Anfrage muss einen `Authorization`-Header mit einem serverseitigen Pushwoosh [API-Zugriffstoken](/de/developer/api-reference/api-access-token/#server-api-token) enthalten:

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="note">
Der Token ist an das Konto gebunden, dem er gehört. Alle Operationen gelten für dieses Konto. Verwenden Sie denselben Token, den Sie auch für andere Server-zu-Server-API-Aufrufe ausstellen, und geben Sie ihn niemals in Client-Anwendungen preis.
</Aside>

## Methoden

### Journeys verwalten

- [Lebenszyklus](/de/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. Eine Journey anhand ihrer UUID starten, pausieren, beenden, entwerfen oder archivieren.
- [Erstellen und Aktualisieren](/de/developer/api-reference/customer-journey-api/create-update/): `POST /api/v3/journeygateway` und `PUT /api/v3/journeygateway/{uuid}`. Eine neue Journey-Definition erstellen oder eine bestehende ersetzen.

### Journeys auslösen

- [Start über API](/de/developer/api-reference/customer-journey-api/start-by-api/): `POST /api/journey/{id}/start/external`. Benutzer in den API-Einstiegspunkt einer bereits laufenden Journey einschleusen.

### Statistiken und Zielgruppe

- [Journey-Statistiken abrufen](/de/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. Zustellungs- und Konversionsmetriken pro Punkt.
- [Benutzer aus Journeys entfernen](/de/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. Benutzer aus allen oder ausgewählten aktiven Journeys entfernen.

### Referenz

- [Journey-Objekt](/de/developer/api-reference/customer-journey-api/journey-object/): die Form der Journey-Definition (Info, Parameter, Punkte, Kommentare), die von den Lebenszyklus-, Erstellungs- und Aktualisierungsmethoden zurückgegeben wird.
- [Punkt-Referenz](/de/developer/api-reference/customer-journey-api/point-reference/): die `point_data`-Struktur für jeden Punkttyp: Einstiegs-, Zeit-, Aufteilungs-, Aktions- und Nachrichtenelemente.

## Lebenszyklus-Start vs. Start über API

Customer Journey hat zwei Operationen, die ähnlich klingen, sich aber unterschiedlich verhalten.

[Lebenszyklus-Start](/de/developer/api-reference/customer-journey-api/lifecycle/#endpoints) ändert den Journey-Status (zum Beispiel von Entwurf zu **Wird ausgeführt**).
[Start über API](/de/developer/api-reference/customer-journey-api/start-by-api/) schleust Benutzer in eine bereits laufende Journey ein. Die folgende Tabelle vergleicht sie nebeneinander.

| | Lebenszyklus-Start | Start über API |
|---|---|---|
| Endpunkt | `POST /api/v3/journeygateway/start` | `POST /api/journey/{id}/start/external` |
| Was es tut | Aktiviert die Journey und versetzt sie in den Status **Wird ausgeführt** | Schleust Benutzer in den **API-Einstiegspunkt** einer bereits laufenden Journey ein |
| Erforderlicher Journey-Status | Entwurf oder Pausiert | Wird ausgeführt (mit einem API-Startpunkt) |
| Ausführungshäufigkeit | Einmal pro Statusänderung | Wiederholt, wenn Benutzer eintreten müssen |

## Anfrage- und Antwortformat

- Inhaltstyp: `application/json`.
- Die `v3`-Feldnamen verwenden `snake_case`. Enum-Werte werden als ihre String-Namen serialisiert (zum Beispiel `"STATUS_RUNNING"`, `"POINT_TYPE_SEND_PUSH"`).
- Die gRPC-Gateway-Methoden (`/api/v3/journeygateway/...`) geben bei Erfolg das [Journey-Objekt](/de/developer/api-reference/customer-journey-api/journey-object/) zurück und bei einem Fehler die standardmäßige gRPC-Gateway-Fehlerhülle: `{ "code": ..., "message": ..., "details": [...] }`.
- Die älteren externen Methoden (`/api/journey/...`) geben bei Erfolg einen methodenspezifischen JSON-Body zurück und `{ "success": false, "message": ... }` mit HTTP `400` bei Validierungsfehlern.

## Schnellstart

```bash title="Eine Journey starten"
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" }'
```

## Nächste Schritte

<CardGrid>
  <LinkCard title="Lebenszyklus" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Erstellen und Aktualisieren" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Start über API" href="/developer/api-reference/customer-journey-api/start-by-api/" />
  <LinkCard title="Journey-Statistiken abrufen" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Benutzer aus Journeys entfernen" href="/developer/api-reference/customer-journey-api/drop-users/" />
  <LinkCard title="Journey-Objekt" href="/developer/api-reference/customer-journey-api/journey-object/" />
  <LinkCard title="Punkt-Referenz" href="/developer/api-reference/customer-journey-api/point-reference/" />
</CardGrid>