--- title: "Connecteur Jira" description: "Guide complet d'intégration Jira Cloud pour synchroniser issues, projets et données d'activité d'équipe avec Brevo via Tajo." url: https://tajo.io/fr/docs/connectors/custom/jira/ markdown: https://tajo.io/fr/docs/connectors/custom/jira.md lang: fr-FR robots: noindex --- Demandez un accès anticipé Indiquez votre prénom et votre adresse e-mail professionnelle. Nous vous enverrons un lien pour confirmer votre demande d’accès à Tajo. # Connecteur Jira Statut du connecteur: Prévu Pas encore construit. Tajo n'exécute pas ce connecteur aujourd'hui. | Champ source | Champ de destination | Valeur d’exemple | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Connectez votre instance Jira Cloud à Brevo pour le suivi des tickets côté client, la visibilité des tickets de support et les notifications de jalons de projet via Tajo. ## Vue d’ensemble | Propriété | Valeur | | --- | --- | | **Plateforme** | Jira Cloud | | **Catégorie** | Custom | | **Complexité d’installation** | Modérée | | **Intégration officielle** | Non | | **Données synchronisées** | Issues, projets, utilisateurs, événements | | **Type d’API** | API REST v3 | | **Authentification** | OAuth 2.0 (3LO) / API Token (Basic Auth) | | **URL de base** | `https://your-domain.atlassian.net/rest/api/3/` | ## Fonctionnalités - **Synchronisation d’événements issue**, Transférez les événements de création, mise à jour et résolution d’issues vers les timelines de contacts Brevo - **Suivi des tickets clients**, Liez les issues Jira aux contacts Brevo pour la visibilité support - **Alertes de jalons projet**, Déclenchez des campagnes Brevo lors des releases de versions et clôtures de sprints - **Données de capacité d’équipe**, Synchronisez les métriques de charge pour les tableaux de bord opérationnels - **Événements de changement de statut**, Suivez les transitions de workflow d’issue en tant qu’événements Brevo - **Synchronisation des commentaires**, Transférez les commentaires visibles au client vers les journaux d’activité Brevo ## Prérequis Avant de commencer, assurez-vous de disposer de : 1. Une instance Jira Cloud (Jira Software, Jira Service Management ou Jira Work Management) 2. Un accès admin pour créer des applications OAuth ou générer des API tokens 3. L’adresse e-mail du compte Atlassian associée à votre API token 4. Un compte Brevo avec accès API 5. Un compte Tajo avec un abonnement actif ## Authentification Jira Cloud prend en charge plusieurs méthodes d’authentification. ### Option 1 : OAuth 2.0 (3LO), recommandé 1. Rendez-vous sur [developer.atlassian.com](https://developer.atlassian.com/console/myapps/) 2. Cliquez sur **Create** > **OAuth 2.0 integration** 3. Configurez l’URL de callback : `https://app.tajo.io/callbacks/jira` 4. Ajoutez ces scopes : ``` read:jira-work read:jira-user write:jira-work read:me ``` Structure d’URL d’API pour OAuth 2.0 : ``` https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/{resource} ``` ### Option 2 : API Token (Basic Auth) 1. Rendez-vous sur [id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens) 2. Cliquez sur **Create API token** 3. Nommez-le « Tajo Integration » ```bash # Basic Auth : e-mail comme nom d'utilisateur, API token comme mot de passe curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \ -u "email@example.com:$JIRA_API_TOKEN" \ -H "Accept: application/json" ``` Limites des API tokens Les API tokens sont liés à des comptes utilisateurs individuels. Si l’utilisateur est désactivé, l’intégration casse. Utilisez OAuth 2.0 pour les déploiements en production. ### Connexion à Tajo ```bash # Avec OAuth 2.0 tajo connectors install jira \ --client-id $JIRA_CLIENT_ID \ --client-secret $JIRA_CLIENT_SECRET \ --cloud-id $JIRA_CLOUD_ID # Avec API Token tajo connectors install jira \ --site-url your-domain.atlassian.net \ --email admin@example.com \ --api-token $JIRA_API_TOKEN ``` ## Configuration ### Configuration de base ```yaml connectors: jira: enabled: true site_url: "your-domain.atlassian.net" auth_type: "oauth2" # ou "basic" sync: issues: true projects: true users: true comments: true worklogs: false projects: - key: "SUPPORT" sync_to_list: 22 - key: "PRODUCT" sync_to_list: 23 issue_types: - Bug - Story - Task - Support Request ``` ### Mappage des champs Mappez les champs issue et utilisateur Jira vers les attributs Brevo : ```yaml field_mapping: # Champs utilisateur accountId: JIRA_ACCOUNT_ID emailAddress: email displayName: FIRSTNAME # Champs issue mappés vers des événements de contact issue_key: LAST_TICKET_KEY issue_status: LAST_TICKET_STATUS issue_priority: LAST_TICKET_PRIORITY issue_created: LAST_TICKET_DATE resolution: LAST_TICKET_RESOLUTION ``` ## Endpoints API Tajo s’intègre avec les endpoints suivants de l’API REST v3 de Jira Cloud : | Endpoint | Méthode | Objet | | --- | --- | --- | | `/rest/api/3/search` | POST | Rechercher des issues avec JQL | | `/rest/api/3/issue/{issueIdOrKey}` | GET | Obtenir les détails d’une issue | | `/rest/api/3/issue` | POST | Créer une issue | | `/rest/api/3/project` | GET | Lister tous les projets | | `/rest/api/3/project/{projectIdOrKey}` | GET | Obtenir les détails d’un projet | | `/rest/api/3/user/search` | GET | Rechercher des utilisateurs | | `/rest/api/3/myself` | GET | Obtenir l’utilisateur courant | | `/rest/api/3/issue/{issueIdOrKey}/comment` | GET | Obtenir les commentaires d’une issue | | `/rest/api/3/webhook` | POST | Enregistrer des webhooks | | `/rest/api/3/status` | GET | Obtenir tous les statuts | | `/rest/api/3/priority` | GET | Obtenir toutes les priorités | ## Exemples de code ### Initialiser le connecteur ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); await tajo.connectors.connect('jira', { clientId: process.env.JIRA_CLIENT_ID, clientSecret: process.env.JIRA_CLIENT_SECRET, cloudId: process.env.JIRA_CLOUD_ID }); ``` ### Synchroniser les issues de support ```javascript // Synchroniser les issues de support Jira vers des contacts Brevo await tajo.connectors.sync('jira', { type: 'incremental', resources: ['issues'], jql: 'project = SUPPORT AND updated >= -24h', batchSize: 50 }); const status = await tajo.connectors.status('jira'); console.log(status); // { // connected: true, // lastSync: '2024-03-15T12:00:00Z', // issuesTracked: 4560, // projectsMonitored: 3, // usersLinked: 890 // } ``` ### Gérer les webhooks Jira ```javascript app.post('/webhooks/jira', async (req, res) => { const event = req.body; await tajo.connectors.handleWebhook('jira', { event: event.webhookEvent, payload: { issueKey: event.issue?.key, issueType: event.issue?.fields?.issuetype?.name, status: event.issue?.fields?.status?.name, reporter: event.issue?.fields?.reporter?.emailAddress, assignee: event.issue?.fields?.assignee?.emailAddress } }); res.status(200).send('OK'); }); ``` ### Rechercher les issues par client ```javascript // Trouver toutes les issues signalées par un client spécifique const issues = await tajo.connectors.query('jira', { jql: 'reporter = "customer@example.com" ORDER BY created DESC', maxResults: 20, fields: ['summary', 'status', 'priority', 'created'] }); ``` ## Limites de débit Jira Cloud impose des limites de débit pour assurer la stabilité de la plateforme : | Contexte | Limite de débit | | --- | --- | | **API REST** | ~100 requêtes par 10 secondes par utilisateur | | **Requêtes simultanées** | 10 requêtes longues simultanées | | **Opérations groupées** | Varie selon l’endpoint | Pagination Jira utilise une pagination basée sur un offset avec les paramètres `startAt` et `maxResults`. La taille de page par défaut est 50, le maximum 100. Tajo gère la pagination automatiquement. Jira renvoie une réponse `429 Too Many Requests` lorsque les limites de débit sont dépassées, avec un en-tête `Retry-After` indiquant quand réessayer. ## Dépannage ### Problèmes courants | Problème | Cause | Solution | | --- | --- | --- | | 401 Unauthorized | Token invalide ou OAuth expiré | Rafraîchissez le token OAuth ou régénérez l’API token | | 403 Forbidden | Permissions insuffisantes | Vérifiez que l’utilisateur a accès au projet demandé | | Erreurs JQL | Syntaxe de requête invalide | Validez d’abord la JQL dans la recherche d’issues de Jira | | Webhook non reçu | Pare-feu bloquant | Assurez-vous que l’URL du webhook est accessible publiquement | | Champs manquants | Champ absent de la réponse | Ajoutez le champ au paramètre `fields` ou utilisez `expand` | ### Mode debug ```yaml connectors: jira: debug: true log_level: verbose log_api_calls: true ``` ### Tester la connexion ```bash tajo connectors test jira # ✓ API authentication successful # ✓ Project access verified # ✓ Issue search operational # ✓ User lookup available # ✓ Webhook registration active ``` ## Bonnes pratiques 1. **Utilisez OAuth 2.0 en production**, Évite la dépendance à des comptes utilisateurs individuels 2. **Filtrez avec JQL**, Synchronisez uniquement les issues pertinentes pour réduire les appels API 3. **Utilisez les webhooks pour le temps réel**, Évitez le polling ; enregistrez des webhooks pour les changements d’issues 4. **Respectez le format ADF**, Jira v3 utilise Atlassian Document Format pour les champs de texte riche 5. **Mappez projet-vers-liste**, Créez des listes Brevo séparées par projet Jira 6. **Gérez la pagination**, Itérez toujours sur toutes les pages pour des données complètes ## Sécurité - **OAuth 2.0 (3LO)**, Authentification sécurisée basée sur tokens avec tokens de rafraîchissement - **API Token + Basic Auth**, Identifiants encodés en Base64 sur HTTPS - **HTTPS uniquement**, Toutes les communications API chiffrées via TLS 1.2+ - **Accès à portée limitée**, Les scopes OAuth limitent l’accès API aux ressources requises - **Sécurité Atlassian Cloud**, Infrastructure certifiée SOC 2 Type II - **Stockage chiffré**, Identifiants chiffrés au repos dans Tajo ## Ressources associées - [Connecteur GitHub](https://tajo.io/fr/docs/connectors/custom/github) - [Connecteur Linear](https://tajo.io/fr/docs/connectors/custom/linear) - [Connecteur Gorgias](https://tajo.io/fr/docs/connectors/support/gorgias) - [API Contacts Brevo](https://tajo.io/fr/docs/contact-management)