---
title: "Conector de Jira"
description: "Guía completa de integración con Jira Cloud para sincronizar issues, proyectos y datos de actividad del equipo con Brevo a través de Tajo."
url: https://tajo.io/es/docs/connectors/custom/jira/
markdown: https://tajo.io/es/docs/connectors/custom/jira.md
lang: es-ES
robots: noindex
---

Solicita acceso anticipado

Escribe tu nombre y dirección de correo de trabajo. Te enviaremos un enlace para confirmar tu solicitud de acceso a Tajo.

# Conector de Jira

Estado del conector: Planificado Aún no está construido. Tajo no ejecuta este conector hoy.

| Campo de origen | Campo de destino | Valor de ejemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecta tu instancia de Jira Cloud con Brevo para el seguimiento de issues orientadas al cliente, la visibilidad de tickets de soporte y las notificaciones de hitos de proyecto a través de Tajo.

## Resumen

| Propiedad | Valor |
| --- | --- |
| **Plataforma** | Jira Cloud |
| **Categoría** | Personalizada |
| **Complejidad de configuración** | Moderada |
| **Integración oficial** | No |
| **Datos sincronizados** | Issues, Proyectos, Usuarios, Eventos |
| **Tipo de API** | REST API v3 |
| **Autenticación** | OAuth 2.0 (3LO) / API Token (Basic Auth) |
| **URL base** | `https://your-domain.atlassian.net/rest/api/3/` |

## Funcionalidades

- **Sincronización de eventos de issue** - Reenvía los eventos de creación, actualización y resolución de issues a las cronologías de contacto en Brevo
- **Seguimiento de tickets de clientes** - Vincula issues de Jira con contactos de Brevo para la visibilidad de soporte
- **Alertas de hitos de proyecto** - Dispara campañas de Brevo al publicar versiones o completar sprints
- **Datos de capacidad del equipo** - Sincroniza métricas de carga de trabajo para dashboards operativos
- **Eventos de cambio de estado** - Rastrea las transiciones de workflow de issues como eventos de Brevo
- **Sincronización de comentarios** - Reenvía los comentarios visibles al cliente a los registros de actividad de Brevo

## Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una instancia de Jira Cloud (Jira Software, Jira Service Management o Jira Work Management)
2. Acceso de administrador para crear apps OAuth o generar tokens de API
3. El email de la cuenta de Atlassian asociado a tu token de API
4. Una cuenta de Brevo con acceso a la API
5. Una cuenta de Tajo con suscripción activa

## Autenticación

Jira Cloud admite varios métodos de autenticación.

### Opción 1: OAuth 2.0 (3LO) - Recomendado

1. Ve a [developer.atlassian.com](https://developer.atlassian.com/console/myapps/)
2. Haz clic en **Create** > **OAuth 2.0 integration**
3. Configura la URL de callback: `https://app.tajo.io/callbacks/jira`
4. Añade estos scopes:

```
read:jira-work
read:jira-user
write:jira-work
read:me
```

Estructura de URL de la API para OAuth 2.0:

```
https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/{resource}
```

### Opción 2: API Token (Basic Auth)

1. Ve a [id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens)
2. Haz clic en **Create API token**
3. Ponle el nombre “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"
```

Limitaciones de los API Tokens

Los tokens de API están ligados a cuentas de usuario individuales. Si se desactiva el usuario, la integración deja de funcionar. Usa OAuth 2.0 para despliegues en producción.

### Conectar con 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
```

## Configuración

### Configuración 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
```

### Asignación de campos

Asocia los campos de issue y usuario de Jira con los atributos de 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 de la API

Tajo se integra con los siguientes endpoints de la REST API v3 de Jira Cloud:

| Endpoint | Método | Propósito |
| --- | --- | --- |
| `/rest/api/3/search` | POST | Buscar issues con JQL |
| `/rest/api/3/issue/{issueIdOrKey}` | GET | Obtener detalles de una issue |
| `/rest/api/3/issue` | POST | Crear una issue |
| `/rest/api/3/project` | GET | Listar todos los proyectos |
| `/rest/api/3/project/{projectIdOrKey}` | GET | Obtener detalles del proyecto |
| `/rest/api/3/user/search` | GET | Buscar usuarios |
| `/rest/api/3/myself` | GET | Obtener el usuario actual |
| `/rest/api/3/issue/{issueIdOrKey}/comment` | GET | Obtener comentarios de una issue |
| `/rest/api/3/webhook` | POST | Registrar webhooks |
| `/rest/api/3/status` | GET | Obtener todos los estados |
| `/rest/api/3/priority` | GET | Obtener todas las prioridades |

## Ejemplos de código

### Inicializar el 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 soporte

```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
// }
```

### Gestionar webhooks de 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']
});
```

## Límites de velocidad

Jira Cloud aplica límites de velocidad para garantizar la estabilidad de la plataforma:

| Contexto | Límite de velocidad |
| --- | --- |
| **REST API** | ~100 peticiones cada 10 segundos por usuario |
| **Peticiones concurrentes** | 10 peticiones de larga duración concurrentes |
| **Operaciones en lote** | Varía según el endpoint |

Paginación

Jira usa paginación basada en offset con los parámetros `startAt` y `maxResults`. El tamaño de página por defecto es 50 y el máximo 100. Tajo gestiona la paginación automáticamente.

Jira devuelve una respuesta `429 Too Many Requests` cuando se superan los límites de velocidad, con una cabecera `Retry-After` que indica cuándo reintentar.

## Resolución de problemas

### Problemas habituales

| Problema | Causa | Solución |
| --- | --- | --- |
| 401 Unauthorized | Token no válido o OAuth expirado | Refresca el token OAuth o regenera el token de API |
| 403 Forbidden | Permisos insuficientes | Verifica que el usuario tenga acceso al proyecto solicitado |
| Errores de JQL | Sintaxis de consulta no válida | Valida el JQL primero en la búsqueda de issues de Jira |
| No se recibe el webhook | Firewall bloqueando | Asegúrate de que la URL del webhook sea accesible públicamente |
| Campos ausentes | Campo no incluido en la respuesta | Añade el campo al parámetro `fields` o usa `expand` |

### Modo depuración

```yaml
connectors:
  jira:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### Probar la conexión

```bash
tajo connectors test jira
# ✓ API authentication successful
# ✓ Project access verified
# ✓ Issue search operational
# ✓ User lookup available
# ✓ Webhook registration active
```

## Buenas prácticas

1. **Usa OAuth 2.0 en producción** - Evita la dependencia de cuentas de usuario individuales
2. **Filtra con JQL** - Sincroniza solo las issues relevantes para reducir llamadas a la API
3. **Usa webhooks para tiempo real** - Evita el polling; registra webhooks para los cambios de issue
4. **Respeta el formato ADF** - La v3 de Jira usa Atlassian Document Format para los campos de texto enriquecido
5. **Asigna proyecto a lista** - Crea listas separadas de Brevo por cada proyecto de Jira
6. **Gestiona la paginación** - Itera siempre por todas las páginas para obtener los datos completos

## Seguridad

- **OAuth 2.0 (3LO)** - Autenticación segura basada en tokens con refresh tokens
- **API Token + Basic Auth** - Credenciales en Base64 sobre HTTPS
- **Solo HTTPS** - Toda la comunicación con la API se cifra vía TLS 1.2+
- **Acceso con scopes** - Los scopes OAuth limitan el acceso de la API a los recursos necesarios
- **Seguridad de Atlassian Cloud** - Infraestructura certificada SOC 2 Tipo II
- **Almacenamiento cifrado** - Credenciales cifradas en reposo en Tajo

## Recursos relacionados

- [Conector de GitHub](https://tajo.io/es/docs/connectors/custom/github)
- [Conector de Linear](https://tajo.io/es/docs/connectors/custom/linear)
- [Conector de Gorgias](https://tajo.io/es/docs/connectors/support/gorgias)
- [API de contactos de Brevo](https://tajo.io/es/docs/contact-management)