--- title: "Conector Jira" description: "Guia completo de integração do Jira Cloud para sincronizar issues, projetos e dados de atividade de equipe com o Brevo via Tajo." url: https://tajo.io/pt/docs/connectors/custom/jira/ markdown: https://tajo.io/pt/docs/connectors/custom/jira.md lang: pt-BR robots: noindex --- Solicite acesso antecipado Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo. # Conector Jira Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje. | Campo de origem | Campo de destino | Valor de exemplo | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Conecte sua instância Jira Cloud ao Brevo para rastreamento de issues voltado ao cliente, visibilidade de tickets de suporte e notificações de marcos de projeto através do Tajo. ## Visão geral | Propriedade | Valor | | --- | --- | | **Plataforma** | Jira Cloud | | **Categoria** | Personalizado | | **Complexidade de configuração** | Moderada | | **Integração oficial** | Não | | **Dados sincronizados** | Issues, Projetos, Usuários, Eventos | | **Tipo de API** | REST API v3 | | **Autenticação** | OAuth 2.0 (3LO) / API Token (Basic Auth) | | **URL base** | `https://your-domain.atlassian.net/rest/api/3/` | ## Recursos - **Sincronização de eventos de issue** - Encaminhe eventos de criação, atualização e resolução de issues para as timelines de contato do Brevo - **Rastreamento de tickets de clientes** - Vincule issues do Jira a contatos do Brevo para visibilidade de suporte - **Alertas de marcos de projeto** - Dispare campanhas do Brevo em releases de versão e conclusões de sprint - **Dados de capacidade da equipe** - Sincronize métricas de carga de trabalho para dashboards operacionais - **Eventos de mudança de status** - Acompanhe transições de workflow de issue como eventos do Brevo - **Sincronização de comentários** - Encaminhe comentários voltados ao cliente para logs de atividade do Brevo ## Pré-requisitos Antes de começar, certifique-se de que você tem: 1. Uma instância Jira Cloud (Jira Software, Jira Service Management ou Jira Work Management) 2. Acesso de administrador para criar apps OAuth ou gerar tokens de API 3. O e-mail da conta Atlassian associado ao seu token de API 4. Uma conta Brevo com acesso à API 5. Uma conta Tajo com assinatura ativa ## Autenticação O Jira Cloud suporta vários métodos de autenticação. ### Opção 1: OAuth 2.0 (3LO) - Recomendado 1. Acesse [developer.atlassian.com](https://developer.atlassian.com/console/myapps/) 2. Clique em **Create** > **OAuth 2.0 integration** 3. Configure a URL de callback: `https://app.tajo.io/callbacks/jira` 4. Adicione estes escopos: ``` read:jira-work read:jira-user write:jira-work read:me ``` A estrutura de URL da API para OAuth 2.0: ``` https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/{resource} ``` ### Opção 2: API Token (Basic Auth) 1. Acesse [id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens) 2. Clique em **Create API token** 3. Nomeie como “Tajo Integration” ```bash # Basic Auth: email as username, API token as password curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \ -u "email@example.com:$JIRA_API_TOKEN" \ -H "Accept: application/json" ``` Limitações do API Token Tokens de API estão vinculados a contas de usuário individuais. Se o usuário for desativado, a integração quebra. Use OAuth 2.0 para deploys em produção. ### Conectando ao Tajo ```bash # Using OAuth 2.0 tajo connectors install jira \ --client-id $JIRA_CLIENT_ID \ --client-secret $JIRA_CLIENT_SECRET \ --cloud-id $JIRA_CLOUD_ID # Using API Token tajo connectors install jira \ --site-url your-domain.atlassian.net \ --email admin@example.com \ --api-token $JIRA_API_TOKEN ``` ## Configuração ### Configuração básica ```yaml connectors: jira: enabled: true site_url: "your-domain.atlassian.net" auth_type: "oauth2" # or "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 ``` ### Mapeamento de campos Mapeie campos de issue e usuário do Jira para atributos do Brevo: ```yaml field_mapping: # User fields accountId: JIRA_ACCOUNT_ID emailAddress: email displayName: FIRSTNAME # Issue fields mapped to contact events 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 da API O Tajo integra-se com os seguintes endpoints da REST API v3 do Jira Cloud: | Endpoint | Método | Finalidade | | --- | --- | --- | | `/rest/api/3/search` | POST | Buscar issues usando JQL | | `/rest/api/3/issue/{issueIdOrKey}` | GET | Obter detalhes da issue | | `/rest/api/3/issue` | POST | Criar uma issue | | `/rest/api/3/project` | GET | Listar todos os projetos | | `/rest/api/3/project/{projectIdOrKey}` | GET | Obter detalhes do projeto | | `/rest/api/3/user/search` | GET | Buscar usuários | | `/rest/api/3/myself` | GET | Obter usuário atual | | `/rest/api/3/issue/{issueIdOrKey}/comment` | GET | Obter comentários da issue | | `/rest/api/3/webhook` | POST | Registrar webhooks | | `/rest/api/3/status` | GET | Obter todos os status | | `/rest/api/3/priority` | GET | Obter todas as prioridades | ## Exemplos de código ### Inicializar o conector ```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 }); ``` ### Sincronizar issues de suporte ```javascript // Sync Jira support issues to Brevo contacts 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 // } ``` ### Tratar webhooks do 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'); }); ``` ### Buscar issues por cliente ```javascript // Find all issues reported by a specific customer 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 taxa O Jira Cloud aplica limites de taxa para garantir a estabilidade da plataforma: | Contexto | Limite de taxa | | --- | --- | | **REST API** | ~100 requisições por 10 segundos por usuário | | **Requisições concorrentes** | 10 requisições de longa duração concorrentes | | **Operações em massa** | Varia conforme o endpoint | Paginação O Jira usa paginação baseada em offset com os parâmetros `startAt` e `maxResults`. O tamanho de página padrão é 50, máximo é 100. O Tajo trata a paginação automaticamente. O Jira retorna uma resposta `429 Too Many Requests` quando os limites de taxa são excedidos, com um cabeçalho `Retry-After` indicando quando tentar novamente. ## Solução de problemas ### Problemas comuns | Problema | Causa | Solução | | --- | --- | --- | | 401 Unauthorized | Token inválido ou OAuth expirado | Renove o token OAuth ou regere o token de API | | 403 Forbidden | Permissões insuficientes | Verifique se o usuário tem acesso ao projeto solicitado | | Erros de JQL | Sintaxe de consulta inválida | Valide o JQL primeiro na busca de issues do Jira | | Webhook não recebido | Firewall bloqueando | Garanta que a URL do webhook seja publicamente acessível | | Campos ausentes | Campo não está na resposta | Adicione o campo ao parâmetro `fields` ou use `expand` | ### Modo de depuração ```yaml connectors: jira: debug: true log_level: verbose log_api_calls: true ``` ### Testar conexão ```bash tajo connectors test jira # ✓ API authentication successful # ✓ Project access verified # ✓ Issue search operational # ✓ User lookup available # ✓ Webhook registration active ``` ## Melhores práticas 1. **Use OAuth 2.0 para produção** - Evita dependência de contas de usuário individuais 2. **Filtre com JQL** - Sincronize apenas issues relevantes para reduzir chamadas de API 3. **Use webhooks para tempo real** - Evite polling; registre webhooks para mudanças de issue 4. **Respeite o formato ADF** - O Jira v3 usa Atlassian Document Format para campos de texto rico 5. **Mapeie projeto-para-lista** - Crie listas separadas do Brevo por projeto do Jira 6. **Trate a paginação** - Sempre itere por todas as páginas para dados completos ## Segurança - **OAuth 2.0 (3LO)** - Autenticação segura baseada em token com refresh tokens - **API Token + Basic Auth** - Credenciais codificadas em Base64 sobre HTTPS - **Somente HTTPS** - Toda comunicação com a API é criptografada via TLS 1.2+ - **Acesso com escopo** - Escopos OAuth limitam o acesso à API aos recursos necessários - **Segurança do Atlassian Cloud** - Infraestrutura certificada SOC 2 Type II - **Armazenamento criptografado** - Credenciais criptografadas em repouso no Tajo ## Recursos relacionados - [Conector GitHub](https://tajo.io/pt/docs/connectors/custom/github) - [Conector Linear](https://tajo.io/pt/docs/connectors/custom/linear) - [Conector Gorgias](https://tajo.io/pt/docs/connectors/support/gorgias) - [API de contatos do Brevo](https://tajo.io/pt/docs/contact-management)