Aperçu de l'API Customer Journey

L’API Customer Journey permet à un backend de gérer les Customer Journeys de manière programmatique : créer et modifier les définitions de parcours, faire passer les parcours par leur cycle de vie (démarrer, mettre en pause, terminer, brouillon, archiver), déclencher un parcours en cours depuis vos propres systèmes, et extraire les statistiques par parcours.

C’est la même API que le constructeur de Customer Journey utilise, exposée via REST/JSON à travers un pont gRPC-Gateway.

URL de base

Les méthodes gRPC-Gateway et les anciennes méthodes externes sont servies sur des hôtes différents :

Méthodes	URL de base
gRPC-Gateway : /api/v3/journeygateway/... (cycle de vie, création, mise à jour)	https://journey-api.svc-nue.pushwoosh.com
Anciennes méthodes externes : /api/journey/... (démarrage par API, statistiques, suppression d’utilisateurs)	https://journey.pushwoosh.com

Conseil

Si vous utilisez une région dédiée ou un déploiement privé, confirmez les URL de base exactes avec votre Customer Success Manager Pushwoosh.

Authentification

Chaque requête doit inclure un en-tête Authorization avec un jeton d’accès API Pushwoosh côté serveur :

Authorization: Api VOTRE_JETON_API

Note

Le jeton est lié au compte qui le possède. Toutes les opérations s’appliquent à ce compte. Utilisez le même jeton que vous émettez pour d’autres appels API de serveur à serveur, et ne l’exposez jamais dans les applications clientes.

Méthodes

Gérer les parcours

• Cycle de vie : POST /api/v3/journeygateway/{action}. Démarrer, mettre en pause, terminer, mettre en brouillon ou archiver un parcours par son UUID.
• Créer et mettre à jour : POST /api/v3/journeygateway et PUT /api/v3/journeygateway/{uuid}. Créer une nouvelle définition de parcours ou remplacer une existante.

Déclencher les parcours

• Démarrer par API : POST /api/journey/{id}/start/external. Injecter des utilisateurs dans le point d’entrée API d’un parcours déjà en cours.

Statistiques et audience

• Obtenir les statistiques du Journey : GET /api/journey/{id}/statistics/external. Métriques de livraison et de conversion par point.
• Retirer des utilisateurs des parcours : POST /api/journey/drop-users/external. Retirer des utilisateurs de tous les parcours actifs ou de certains d’entre eux.

Référence

• Objet Journey : la forme de la définition du parcours (info, params, points, comments) retournée par les méthodes de cycle de vie, de création et de mise à jour.
• Référence des points : la structure point_data pour chaque type de point : entrée, synchronisation, division, action et éléments de messagerie.

Démarrage du cycle de vie vs Démarrage par API

Customer Journey a deux opérations qui semblent similaires mais se comportent différemment.

Le démarrage du cycle de vie change l’état du parcours (par exemple, de Brouillon à En cours). Le démarrage par API injecte des utilisateurs dans un parcours déjà en cours. Le tableau ci-dessous les compare côte à côte.

	Démarrage du cycle de vie	Démarrage par API
Point de terminaison	POST /api/v3/journeygateway/start	POST /api/journey/{id}/start/external
Ce que ça fait	Active le parcours et le met dans l’état En cours	Injecte des utilisateurs dans le point d’entrée API d’un parcours déjà en cours
État du parcours requis	Brouillon ou En pause	En cours (avec un point de Démarrage API)
Fréquence d’exécution	Une fois par changement d’état	De manière répétée, au fur et à mesure que les utilisateurs doivent entrer

Format des requêtes et des réponses

• Type de contenu : application/json.
• Les noms de champs de la v3 utilisent le snake_case. Les valeurs Enum sont sérialisées sous forme de chaînes de caractères (par exemple, "STATUS_RUNNING", "POINT_TYPE_SEND_PUSH").
• Les méthodes gRPC-Gateway (/api/v3/journeygateway/...) retournent l’objet journey en cas de succès et l’enveloppe d’erreur standard gRPC-Gateway en cas d’échec : { "code": ..., "message": ..., "details": [...] }.
• Les anciennes méthodes externes (/api/journey/...) retournent un corps JSON spécifique à la méthode en cas de succès et { "success": false, "message": ... } avec un code HTTP 400 en cas d’erreurs de validation.

Démarrage rapide

Démarrer un parcours

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

Prochaines étapes

Cycle de vie

Créer et mettre à jour

Démarrer par API

Obtenir les statistiques du Journey

Retirer des utilisateurs des parcours

Objet Journey

Référence des points