Documentación de la API

Todas las solicitudes a la API deben incluir una clave de API válida en el encabezado Authorization usando el esquema Bearer. Las claves de API están vinculadas a un único espacio y están disponibles en el plan Business.

Authorization: Bearer rqp_a1b2c3d4e5f6...

Cómo obtener una clave de API

1. Navega a la configuración de tu espacio
2. Abre la pestaña "Claves de API"
3. Haz clic en "Crear Clave de API" y dale un nombre descriptivo
4. Copia la clave inmediatamente — no se mostrará de nuevo

Crea una nueva solicitud en el espacio asociado a la clave de API.

Cuerpo de la Solicitud

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

Respuesta 201

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

Respuestas de Error

• 401 — Clave de API inválida o ausente
• 403 — La plantilla no pertenece a este espacio
• 422 — Campos requeridos de la plantilla ausentes o datos inválidos
• 429 — Límite de solicitudes excedido

Recupera una lista paginada de solicitudes en el espacio. Soporta filtrado por estado, plantilla, asignado y rango de fechas.

Parámetros de Consulta

Respuesta 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
  }
}

Recupera los detalles completos de una única solicitud, incluyendo todos los valores de campos.

Respuesta 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" }
    ]
  }
}

Respuestas de Error

• 401 — Clave de API inválida o ausente
• 404 — Solicitud no encontrada o pertenece a otro espacio
• 429 — Límite de solicitudes excedido

Actualiza el estado de una solicitud existente. Solo se aceptan transiciones de estado válidas.

Cuerpo de la Solicitud

{
  "status": "in_progress"
}

Transiciones de Estado Válidas

Respuesta 200

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

Respuestas de Error

• 401 — Clave de API inválida o ausente
• 404 — Solicitud no encontrada o pertenece a otro espacio
• 422 — Transición de estado inválida (la respuesta incluye transiciones permitidas)
• 429 — Límite de solicitudes excedido

Los webhooks te permiten recibir notificaciones HTTP POST en tiempo real cuando ocurren eventos en tu espacio. Configura endpoints de webhook en la configuración del espacio (requiere plan Business).

Tipos de Evento

• request_created — Se creó una nueva solicitud
• request_status_changed — Se actualizó el estado de una solicitud
• request_assigned — Se asignó o reasignó una solicitud
• request_closed — Se cerró una solicitud

Formato del 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"
  }
}

Verificación de Firma

Si configuraste un secreto para tu endpoint de webhook, cada entrega incluye un encabezado X-Requester-Signature-256. Verifícalo 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);

Comportamiento de Reintento

Las entregas fallidas (respuesta no-2xx o timeout después de 10s) se reintentan con backoff exponencial:

Después de 5 intentos fallidos, la entrega se marca como fallida. Revisa el log de entregas en la configuración del espacio para solucionar problemas.

La API Pública impone límites de solicitudes para garantizar un uso justo y la estabilidad del sistema.

• 60 solicitudes por minuto por clave de API
• Las respuestas 429 incluyen un encabezado Retry-After indicando los segundos hasta que se permita la siguiente solicitud

Ejemplo de Respuesta 429

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

Implementa backoff exponencial en tu cliente al recibir respuestas 429. Cada clave de API tiene un límite independiente.