Integração e APIs

Visão Geral

O OpsScript oferece múltiplas formas de integração:

MCP server (Model Context Protocol): Acesso às principais funcionalidades do sistema para clientes MCP (IDEs, assistentes com IA). Veja IA e Automação para detalhes.
Webhooks: Envie eventos para seus sistemas
APIs REST: Programe ações customizadas
ChatOps: Controle via plataformas de chat
Integrações Pré-construídas: Slack, Teams, GitHub, etc.

[Assista o vídeo de Integrações e APIs]

Webhook

O que é Webhook?

Um webhook permite que o OpsScript envie automaticamente dados para seus servidores quando algo acontece.

Evento no OpsScript → POST JSON → Seu Servidor
(Chamado criado)     (URL webhook) (Processa notificação)

Configurar Webhook

Configuração → Integrações → Webhooks
+ Novo Webhook
Preencha:
- Nome: Identificador (ex: "Slack Backup")
- URL: Seu servidor (ex: https://seu-dominio.com/webhook)
- Eventos: Selecione quais eventos disparam
Testar: Envie teste antes de salvar
Salve

Eventos Disponíveis

Chamados:
- ticket.created: Novo chamado criado
- ticket.updated: Chamado atualizado
- ticket.assigned: Atribuído para alguém
- ticket.status_changed: Mudou de estado
- ticket.closed: Fechado
- ticket.comment_added: Adicionada nota

Projetos:
- project.created: Novo projeto
- sprint.started: Sprint iniciada
- sprint.completed: Sprint finalizada
- task.completed: Tarefa concluída

Usuários:
- user.invited: Novo membro convidado
- user.left: Membro saiu

Payload (Dados Enviados)

Exemplo de webhook para "ticket.created":

{
  "event": "ticket.created",
  "timestamp": "2024-11-25T10:30:00Z",
  "ticket": {
    "id": "OPS-123",
    "title": "Servidor Down",
    "priority": "critical",
    "assignee": "joao@company.com",
    "created_by": "maria@company.com",
    "category": "infrastructure",
    "description": "Web server não responde"
  }
}

Segurança de Webhook

Validação de Assinatura

Cada webhook contém header de validação:

X-OpsScript-Signature: sha256=abc123def456...

Para validar (pseudocódigo):

import hmac
import hashlib

signature = request.headers['X-OpsScript-Signature']
payload = request.body
secret = "sua_webhook_secret"

# Calcular assinatura esperada
expected = 'sha256=' + hmac.new(
    secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

# Validar
if signature == expected:
    # Processou legítimo
    process_webhook()
else:
    # Rejeitar
    return 401

Retry

OpsScript tentará novamente se falhar:

1ª tentativa: Imediata
2ª tentativa: 5 minutos depois
3ª tentativa: 1 hora depois
4ª tentativa: 24 horas depois
Depois: Desativa

[Assista o vídeo de Webhooks Avançados]

API REST

Autenticação

Obtenha token:

Configuração → API → Tokens
+ Novo Token
Preencha:
- Nome: Para que serve (ex: "Script de automação")
- Permissões: Selecione o que pode fazer
- Expiração: Quando expira
Copie token
Salve em local seguro (não será mostrado novamente)

Headers Obrigatórios

Authorization: Bearer seu_token_aqui
Content-Type: application/json

Endpoints Principais

Listar Chamados

GET /api/v1/tickets

Query Parameters:
  ?state=open
  ?priority=critical
  ?assigned_to=joao@company.com
  ?limit=10&offset=0

Resposta:
{
  "data": [
    {
      "id": "OPS-123",
      "title": "Servidor Down",
      "priority": "critical",
      "state": "open",
      "assignee": "joao@company.com",
      "created_at": "2024-11-25T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

Criar Chamado

POST /api/v1/tickets

Body:
{
  "title": "Novo chamado",
  "description": "Descrição detalhada",
  "priority": "high",
  "category": "infrastructure",
  "assigned_to": "joao@company.com"
}

Resposta:
{
  "id": "OPS-125",
  "title": "Novo chamado",
  "priority": "high",
  "state": "new",
  "created_at": "2024-11-25T11:00:00Z"
}

Atualizar Chamado

PUT /api/v1/tickets/OPS-125

Body:
{
  "state": "in_progress",
  "priority": "critical"
}

Resposta:
{
  "id": "OPS-125",
  "state": "in_progress",
  "priority": "critical",
  "updated_at": "2024-11-25T11:05:00Z"
}

Adicionar Comentário

POST /api/v1/tickets/OPS-125/comments

Body:
{
  "content": "Trabalho em progresso",
  "public": false
}

Resposta:
{
  "id": "comment_456",
  "content": "Trabalho em progresso",
  "created_by": "joao@company.com",
  "created_at": "2024-11-25T11:10:00Z"
}

Buscar Projeto

GET /api/v1/projects/OPS

Resposta:
{
  "id": "OPS",
  "name": "OpsScript",
  "description": "Main project",
  "methodology": "scrum",
  "members": ["joao@", "maria@"],
  "created_at": "2024-11-25T10:00:00Z"
}

Listar Sprints

GET /api/v1/projects/OPS/sprints

Resposta:
{
  "data": [
    {
      "id": "sprint_1",
      "name": "Sprint 1",
      "start_date": "2024-11-25",
      "end_date": "2024-12-08",
      "status": "active",
      "goals": "Performance improvements"
    }
  ]
}

[Assista o vídeo de APIs REST]

Erros

Códigos de status HTTP padrão:

200 OK: Sucesso
201 Created: Recurso criado
400 Bad Request: Dados inválidos
401 Unauthorized: Token inválido
403 Forbidden: Sem permissão
404 Not Found: Recurso não encontrado
429 Too Many Requests: Rate limit excedido
500 Internal Server Error: Erro do servidor

Exemplo de erro:

{
  "error": "validation_error",
  "message": "Título é obrigatório",
  "details": {
    "field": "title",
    "code": "required"
  }
}

Rate Limiting

Limites por token:

Tier | Requisições/Minuto
-----|-------------------
Free | 60
Pro  | 300
Enterprise | Ilimitado

Headers de resposta:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1700000000

Exemplos Práticos

Script de Escalação

import requests
import time

api_token = "seu_token_aqui"
headers = {
    "Authorization": f"Bearer {api_token}",
    "Content-Type": "application/json"
}

# Buscar todos os chamados críticos abertos
response = requests.get(
    "https://opscript.com/api/v1/tickets",
    params={"priority": "critical", "state": "open"},
    headers=headers
)

tickets = response.json()["data"]

for ticket in tickets:
    # Se aberto há mais de 30 minutos
    created = ticket["created_at"]
    age_minutes = (time.time() - parse_timestamp(created)) / 60

    if age_minutes > 30:
        # Escalar para gerente
        requests.put(
            f"https://opscript.com/api/v1/tickets/{ticket['id']}",
            json={
                "assigned_to": "gerente@company.com",
                "state": "in_progress"
            },
            headers=headers
        )

        # Adicionar nota
        requests.post(
            f"https://opscript.com/api/v1/tickets/{ticket['id']}/comments",
            json={
                "content": "Escalado automaticamente após 30 minutos",
                "public": False
            },
            headers=headers
        )

Criar Chamado de Alerta

def create_alert_ticket(alert_name, severity, description):
    """Cria chamado a partir de alerta de monitoramento"""

    api_token = os.getenv("OPSCRIPT_API_TOKEN")

    priority_map = {
        "critical": "critical",
        "warning": "high",
        "info": "medium"
    }

    response = requests.post(
        "https://opscript.com/api/v1/tickets",
        headers={
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json"
        },
        json={
            "title": f"[ALERTA] {alert_name}",
            "description": description,
            "priority": priority_map.get(severity, "medium"),
            "category": "infrastructure",
            "tags": ["alerta", severity]
        }
    )

    if response.status_code == 201:
        ticket = response.json()
        print(f"Chamado criado: {ticket['id']}")
        return ticket
    else:
        print(f"Erro: {response.json()}")
        return None

[Assista o vídeo de Integração com Scripts]

Integrações Pré-construídas

Slack

Configuração → Integrações → Slack
Clique Conectar com Slack
Selecione workspace
Authorize
Configure canais para notificações
Salve

Comandos no Slack:

/opscript ticket OPS-123
/opscript assign OPS-123 @joao
/opscript create "Novo chamado via Slack"

GitHub/GitLab

Configuração → Integrações → Repositório
Conecte a conta
Selecione repositórios
Configure sincronização

Funcionalidades:

Vincular commits a chamados
Criar PRs de tarefas
Deploy automático ao mesclar

Jira (Migração)

Para usuários migrando do Jira:

Configuração → Importação
Selecione Jira
Conecte instância Jira
Mapeie tipos de issue
Importe dados históricos

[Assista o vídeo de Migrações de Outras Ferramentas]

Desenvolvendo Integrações Customizadas

Cliente SDK (TypeScript/JavaScript)

import { OpsScriptClient } from '@opscript/sdk';

const client = new OpsScriptClient({
  apiToken: process.env.OPSCRIPT_API_TOKEN,
  baseUrl: 'https://opscript.com'
});

// Criar chamado
const ticket = await client.tickets.create({
  title: 'Novo chamado',
  priority: 'high',
  category: 'infrastructure'
});

// Listar meus chamados
const myTickets = await client.tickets.list({
  assignedTo: 'meu@email.com'
});

// Atualizar status
await client.tickets.update(ticket.id, {
  state: 'in_progress'
});