Integração Jira
O MIDDAG Account integra-se ao Jira Service Management para rastreamento de solicitações de serviço, monitoramento de SLA e gerenciamento de worklogs. O Jira é o motor de SLA -- o plugin exibe o status do SLA e agrega dados para relatórios, mas não executa seu próprio relógio de SLA.
Princípio central
O Jira aplica os SLAs (pausar/retomar, calendários, feriados). O plugin espelha o status. Executar relógios de SLA paralelos criaria divergência e exigiria a manutenção de dois motores de temporização. O Jira é a fonte única da verdade para o estado de SLA.
Configuração
Credenciais da API
| Variável | Descrição | Obrigatório |
|---|---|---|
JIRA_DOMAIN | Domínio Atlassian (ex.: middag) | Sim |
JIRA_EMAIL | E-mail do usuário de integração | Sim |
JIRA_API_TOKEN | Token de API do usuário de integração | Sim |
O plugin conecta-se ao Jira Cloud em https://{JIRA_DOMAIN}.atlassian.net/rest/api/3. A autenticação utiliza HTTP Basic com e-mail e token de API.
Degradação graciosa
Se as variáveis de ambiente não estiverem definidas, a integração com o Jira é silenciosamente desabilitada. Todos os métodos de serviço do Jira retornam graciosamente, e o restante do plugin funciona normalmente. Este é o mesmo padrão usado para todas as integrações opcionais.
Fluxo de dados: Jira para Plugin
O Jira envia webhooks para o plugin em eventos de ciclo de vida de issues:
Reconciliação periódica
Um cron job captura webhooks perdidos:
| Frequência | Ação |
|---|---|
| A cada 15 min | Verificar SRs com status divergente |
| Diário | Reconciliar campos de SLA para todos os SRs abertos |
| Semanal | Gerar relatório de conformidade de SLA |
Fluxo de dados: Plugin para Jira
O plugin também cria e gerencia issues no Jira.
Criação automática de issues a partir de pedidos
Quando um pedido WooCommerce é finalizado, o plugin verifica cada item do pedido para configuração Jira. Se um produto possui _middag_jira_enabled = yes, o plugin cria uma issue no Jira automaticamente.
Chaves de meta do produto para configuração do Jira:
| Chave | Descrição |
|---|---|
_middag_jira_enabled | Habilitar criação de issue no Jira (yes/no) |
_middag_jira_project_key | Chave do projeto Jira (ex.: MIDDAG) |
_middag_jira_issue_type_id | ID do tipo de issue |
_middag_jira_summary_template | Template opcional para o resumo |
Endpoints da REST API
O plugin expõe operações do Jira através de sua própria REST API:
| Método | Endpoint | Descrição |
|---|---|---|
| GET | /jira/projects | Listar projetos Jira |
| GET | /jira/projects/{key}/issue-types | Tipos de issue de um projeto |
| POST | /jira/issues | Criar uma issue |
| GET | /jira/issues/{key} | Obter uma issue por chave |
| PUT | /jira/issues/{key} | Atualizar uma issue |
| GET | /jira/issues/search?jql=... | Busca JQL |
| POST | /jira/issues/{key}/transitions | Transicionar uma issue |
| POST | /jira/issues/{key}/comments | Adicionar um comentário |
Todos os endpoints possuem o prefixo middag-account/v1.
Fonte da verdade por tipo de dado
| Dado | Fonte da verdade | Direção |
|---|---|---|
| Status da issue | Jira | Jira para Plugin |
| Prioridade | Jira | Jira para Plugin |
| Tempo decorrido de SLA | Jira | Jira para Plugin |
| Eventos de violação de SLA | Jira | Jira para Plugin |
| UST estimada | Plugin | Plugin para Jira |
| UST real | Plugin | Calculada |
| Valor faturado | Plugin | Não sincronizado |
| Tipo de serviço | Plugin | Plugin para Jira |
| Subtarefas e boards | Jira | Não sincronizado |
Rastreamento de worklogs
Os worklogs do Jira alimentam os cálculos de UST (unidade de tempo de serviço) do plugin. Quando uma solicitação de serviço é resolvida, o plugin lê os worklogs do Jira e calcula o tempo real gasto. Esses dados são usados para faturamento e relatórios de conformidade de SLA.
Limitação de taxa
O cliente Jira respeita respostas HTTP 429 com headers Retry-After. Máximo de 3 tentativas de retentativa com o atraso especificado pelo Jira. O timeout de requisição é de 30 segundos.