Documentação da API

Todas as requisições da API devem incluir uma chave de API válida no cabeçalho Authorization usando o esquema Bearer. As chaves de API são vinculadas a um único espaço e estão disponíveis no plano Business.

Authorization: Bearer rqp_a1b2c3d4e5f6...

Como obter uma chave de API

1. Navegue até as configurações do seu espaço
2. Abra a aba "Chaves de API"
3. Clique em "Criar Chave de API" e dê um nome descritivo
4. Copie a chave imediatamente — ela não será exibida novamente

Crie uma nova solicitação no espaço associado à chave de API.

Corpo da Requisição

{
  "templateId": "tpl_abc123",
  "fields": [
    { "fieldId": "field_1", "value": "Server is down" },
    { "fieldId": "field_2", "value": "high" }
  ],
  "priority": "high",
  "assignedToId": "user_xyz"
}

Resposta 201

{
  "data": {
    "id": "req_def456",
    "status": "todo",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Respostas de Erro

• 401 — Chave de API inválida ou ausente
• 403 — Modelo não pertence a este espaço
• 422 — Campos obrigatórios do modelo ausentes ou dados inválidos
• 429 — Limite de requisições excedido

Recupere uma lista paginada de solicitações no espaço. Suporta filtragem por status, modelo, responsável e intervalo de datas.

Parâmetros de Consulta

Resposta 200

{
  "data": [
    {
      "id": "req_def456",
      "templateId": "tpl_abc123",
      "status": "in_progress",
      "priority": "high",
      "assignedToId": "user_xyz",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

Recupere os detalhes completos de uma única solicitação, incluindo todos os valores dos campos.

Resposta 200

{
  "data": {
    "id": "req_def456",
    "templateId": "tpl_abc123",
    "status": "in_progress",
    "priority": "high",
    "assignedToId": "user_xyz",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T11:00:00.000Z",
    "fieldValues": [
      { "fieldId": "field_1", "name": "Description", "value": "Server is down" },
      { "fieldId": "field_2", "name": "Category", "value": "high" }
    ]
  }
}

Respostas de Erro

• 401 — Chave de API inválida ou ausente
• 404 — Solicitação não encontrada ou pertence a outro espaço
• 429 — Limite de requisições excedido

Atualize o status de uma solicitação existente. Apenas transições de status válidas são aceitas.

Corpo da Requisição

{
  "status": "in_progress"
}

Transições de Status Válidas

Resposta 200

{
  "data": {
    "id": "req_def456",
    "status": "in_progress",
    "previousStatus": "todo",
    "updatedAt": "2024-01-15T11:00:00.000Z"
  }
}

Respostas de Erro

• 401 — Chave de API inválida ou ausente
• 404 — Solicitação não encontrada ou pertence a outro espaço
• 422 — Transição de status inválida (resposta inclui transições permitidas)
• 429 — Limite de requisições excedido

Webhooks permitem que você receba notificações HTTP POST em tempo real quando eventos ocorrem no seu espaço. Configure endpoints de webhook nas configurações do espaço (plano Business necessário).

Tipos de Evento

• request_created — Uma nova solicitação foi criada
• request_status_changed — O status de uma solicitação foi atualizado
• request_assigned — Uma solicitação foi atribuída ou reatribuída
• request_closed — Uma solicitação foi fechada

Formato do Payload

{
  "id": "del_abc123",
  "type": "request_status_changed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "space": {
    "id": "space_xyz",
    "slug": "engineering"
  },
  "data": {
    "requestId": "req_def456",
    "templateId": "tpl_abc123",
    "status": "in_progress",
    "previousStatus": "todo",
    "assignedToId": "user_xyz",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Verificação de Assinatura

Se você configurou um segredo para seu endpoint de webhook, cada entrega inclui um cabeçalho X-Requester-Signature-256. Verifique usando HMAC-SHA256:

import crypto from 'crypto';

function verifySignature(payload: string, secret: string, signature: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Usage in your webhook handler:
const signature = req.headers['x-requester-signature-256'];
const isValid = verifySignature(rawBody, yourSecret, signature);

Comportamento de Retentativa

Entregas com falha (resposta não-2xx ou timeout após 10s) são retentadas com backoff exponencial:

Após 5 tentativas com falha, a entrega é marcada como falhou. Verifique o log de entregas nas configurações do espaço para solucionar problemas.

A API Pública impõe limites de requisições para garantir uso justo e estabilidade do sistema.

• 60 requisições por minuto por chave de API
• Respostas 429 incluem um cabeçalho Retry-After indicando segundos até a próxima requisição ser permitida

Exemplo de Resposta 429

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after the specified duration."
  }
}

Implemente backoff exponencial no seu cliente ao receber respostas 429. Cada chave de API tem um limite independente.