API, webhooks et SSO des retours

L’API d’intégration reçoit des tickets ou des retours depuis un serveur, avec des clés propres au projet. Les intégrations de tickets peuvent aussi envoyer des webhooks signés ; le SSO des visiteurs des retours utilise un secret distinct du tableau. Suivez les contrôles des points d’accès, de l’identité et de la livraison : les clés restent sur le serveur et les jetons de redirection SSO ne doivent pas figurer dans les journaux partagés.

Créer tickets ou feedback et recevoir des webhooks signés

Le propriétaire crée une intégration avec Nouvelle intégration sur la ligne de titre de Paramètres du projet → Intégrations. Choisissez issues pour les tâches internes en triage, feedback pour les besoins utilisateur avec votes/statut public. La clé mdy_ en clair apparaît une fois. Gardez-la uniquement côté serveur, dans MINDDY_API_KEY ou MINDDY_FEEDBACK_KEY, jamais navigateur, dépôt ou journaux partagés. Chaque intégration est listée avec son nom, le préfixe de sa clé, sa date de création, sa dernière utilisation et un badge Tickets ou Retours. Pour en révoquer une, le propriétaire choisit Révoquer dans son menu ⋯ et confirme ; elle porte alors le badge Révoquée et passe en fin de liste, estompée. La révocation est définitive ; clés inconnues/révoquées retournent 401 invalid_api_key. La clé appartient à un projet et ne peut appeler l’autre famille d’endpoints (403 wrong_key_kind). Une intégration n’est pas une personne : elle n’a aucun rôle dans le projet et garde les permissions fixes de son type lorsque les rôles des membres changent. Les lecteurs ne voient pas les intégrations.

Envoyer les champs corrects

Utilisez GET /api/v1/issues/options pour obtenir les identifiants des catégories du projet et les valeurs de priorité et d’effort. Envoyez ensuite POST /api/v1/issues avec un titre non vide et, si nécessaire, une description Markdown, une priorité, un effort et des catégories.

Le ticket créé entre toujours en triage ; son statut, son responsable et son parent ne sont pas réglables de l’extérieur. La réponse 201 contient id, number, identifier et status. Pour les champs des retours, les contrôles d’identité et la modération, suivez la procédure d’ingestion des retours.

curl --fail-with-body --request POST "$MINDDY_ORIGIN/api/v1/issues" \
  --header "Authorization: Bearer $MINDDY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"title":"Rapport de démonstration","description":"Reproduire avec des données de démonstration","priority":"low","effort":"s"}'

Vérifier et dédupliquer les événements

Une intégration issues envoie issue.created, issue.status_changed et issue.updated. Le propriétaire choisit toute nouvelle destination avec Configurer le webhook… dans le menu ⋯ de l’intégration. Une fois la destination définie, la ligne Webhook sous l’intégration indique la dernière livraison, acceptée ou refusée avec sa date, ou Aucune livraison pour le moment. Les agents peuvent régler événements/périmètre existants ou désactiver, sans créer de nouveau canal sortant. Le périmètre integration limite aux tickets de cette clé ; all couvre tout le projet. Vérifiez X-minddy-Signature : sha256= suivi de HMAC-SHA256 sur les octets bruts reçus, avec comme clé le digest SHA-256 hexadécimal minuscule de la clé API. Comparez en temps constant avant de croire le contenu. Ne parsez/résérialisez pas avant le hash. X-minddy-Delivery correspond à delivery_id ; dédupliquez par UUID.

Traiter les échecs et limites

La livraison est sans garantie : délai de cinq secondes et une tentative immédiate après erreur réseau ou 5xx, puis abandon définitif. Doublons et désordre sont possibles. Persistez le contenu vérifié, retournez 2xx rapidement et traitez après. issue.updated regroupe les changements ; description et plan indiquent le champ sans sa valeur. Vérifiez le dernier statut dans les paramètres. Pour 429, respectez Retry-After. Les erreurs de validation sont 422 ; un quota atteint est un 403 issue_limit_reached définitif. Une création dont la réponse a expiré peut avoir abouti : contrôlez le résultat avant de réessayer. Le vote sur les retours possède son point d’accès et ses limites.

Connecter ingestion des retours et SSO visiteurs

Le propriétaire du projet crée une clé d’intégration feedback dans les réglages du projet. Enregistrez la clé, affichée une seule fois, sous MINDDY_FEEDBACK_KEY dans la configuration secrète de votre backend. Ne l’intégrez jamais au code du navigateur. Définissez MINDDY_ORIGIN sur l’origine de l’instance cible, sans barre oblique finale.

curl -i "$MINDDY_ORIGIN/api/v1/feedback"   -H "Authorization: Bearer $MINDDY_FEEDBACK_KEY"   -H 'Content-Type: application/json'   --data '{"title":"Afficher la date de livraison","body":"Le support a besoin de la date prévue.","user":{"external_id":"demo-user-1","name":"Lecteur de démonstration"}}'

Fournissez un titre non vide de 200 caractères maximum, un corps facultatif de 10 000 caractères maximum et user.external_id et/ou user.email. user.name est facultatif. L’identifiant externe accepte 255 caractères, l’email 254 et le nom 200. Votre backend garantit l’identité transmise ; l’ingestion anonyme est refusée. Le succès renvoie HTTP 201 avec id, status, review_state, les votes et le pseudonyme. Le board n’a pas besoin d’être activé pour l’ingestion. analyze est un booléen qui vaut true par défaut ; la chaîne "false" est refusée. Définissez-le sur false pour ignorer la modération, la catégorisation et la fusion des doublons de ce retour et lui donner l’état de revue published sans attente. Cet état de revue n’active pas le board et ne contourne pas les règles de visibilité du retour ou son statut spam. L’API crée les retours publics par défaut et n’accepte pas de paramètre de visibilité privée.

Votes, erreurs et webhooks

Envoyez {"user":{"external_id":"demo-user-1"}} par POST à /api/v1/feedback/<id>/vote, avec les mêmes en-têtes. Chaque identité dispose d’un vote ; répéter ce vote est idempotent. Un retour fusionné renvoie 409 post_merged et indique sa cible canonique.

La création autorise 20 appels par minute et par clé ; le vote, 60. Respectez Retry-After après 429. Vérifiez 401 invalid_api_key, 403 wrong_key_kind, 400 invalid_json et les erreurs de champs 422 avant de réessayer. La création n’est pas une mise à jour idempotente : si la réponse est perdue, vérifiez la boîte de retours de l’équipe avant de répéter. Les clés feedback n’ont pas de webhook sortant de tickets. Une intégration tickets configurée séparément fournit ce canal, avec sa signature et son contrat de livraison sans garantie.

Identifier les visiteurs par SSO

En tant que propriétaire, activez le board et configurez son secret SSO distinct. Votre backend signe un JWT HS256 avec un sub stable, un exp obligatoire et un email et un nom facultatifs. Limitez sa validité à 600 secondes et utilisez un jti unique ; la vérification tolère un décalage d’horloge de 60 secondes. Redirigez immédiatement vers /f/<board-token>?sso=<jwt>. Un token n’est consommable qu’une fois par board ; une nouvelle tentative exige un token fraîchement signé. Ne réutilisez jamais la clé d’ingestion comme secret SSO. Gardez les tokens hors des journaux et captures partagées.

Vérifiez que le visiteur ouvre Mes retours avec l’identité prévue. Un token expiré exige une nouvelle redirection. Si le secret est compromis, renouvelez-le avec la confirmation du board et mettez à jour le backend en même temps. Le parcours par code email reste disponible lorsque le SSO ne l’est pas.

Choisir un objectif pour un retour

Pour une intégration feedback, le propriétaire peut choisir l’objectif à la création, ou plus tard sur la ligne Objectif des nouveaux retours sous l’intégration existante dans Paramètres du projet → Intégrations ; ce sélecteur peut aussi créer un nouvel objectif. Seul un objectif actif du même projet est accepté. Chaque nouvel envoi POST /api/v1/feedback hérite de ce réglage, y compris avec analyze: false ; n’envoyez pas objective_id dans le corps de la requête. La réponse 201 contient l’objective_id associé ou null. Modifier ou retirer le réglage affecte uniquement les futurs envois. Un objectif indisponible provoque une réponse 422 objective_not_found : choisissez un objectif actif ou retirez le réglage avant de réessayer. La revue Numo ne déduit pas les objectifs. La conversion reprend l’objectif et les catégories du retour.