Visión General de la API

La API de GitScrum proporciona acceso programático a los datos de tu workspace. Construye integraciones personalizadas, automatiza flujos de trabajo, crea informes o construye interfaces completamente nuevas sobre GitScrum.

Comenzar

URL Base

https://services.gitscrum.com/v1

Autenticación

Todas las solicitudes requieren una clave API en el encabezado:

Authorization: Bearer tu_clave_api_aqui

Generar Clave API

1. Ve a Configuración del Workspace > API
2. Haz clic en "Generar Clave API"
3. Nombra la clave descriptivamente
4. Copia inmediatamente (se muestra solo una vez)
5. Almacena de forma segura

Límites de Tasa

Encabezados de límite en cada respuesta:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1705320000

Formato de Respuesta

Todas las respuestas son JSON:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150
  }
}

Respuestas de Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tarea no encontrada",
    "details": { ... }
  }
}

Códigos de Estado HTTP

Endpoints Principales

Workspaces

GET    /workspaces              # Listar workspaces
GET    /workspaces/:id          # Obtener detalles
PUT    /workspaces/:id          # Actualizar

Proyectos

GET    /workspaces/:id/projects         # Listar proyectos
POST   /workspaces/:id/projects         # Crear proyecto
GET    /projects/:id                     # Obtener proyecto
PUT    /projects/:id                     # Actualizar
DELETE /projects/:id                     # Eliminar

Tareas

GET    /projects/:id/tasks      # Listar tareas
POST   /projects/:id/tasks      # Crear tarea
GET    /tasks/:id               # Obtener tarea
PUT    /tasks/:id               # Actualizar
DELETE /tasks/:id               # Eliminar
PATCH  /tasks/:id/move          # Mover tarea

Miembros del Equipo

GET    /workspaces/:id/members  # Listar miembros
POST   /workspaces/:id/members  # Invitar
DELETE /members/:id             # Eliminar

Entradas de Tiempo

GET    /tasks/:id/time-entries  # Listar tiempo
POST   /time-entries            # Crear entrada
PUT    /time-entries/:id        # Actualizar
DELETE /time-entries/:id        # Eliminar

Sprints

GET    /projects/:id/sprints    # Listar sprints
POST   /projects/:id/sprints    # Crear sprint
PUT    /sprints/:id             # Actualizar
POST   /sprints/:id/start       # Iniciar
POST   /sprints/:id/end         # Terminar

Parámetros de Consulta

Paginación

GET /projects/:id/tasks?page=2&per_page=50

• page: Número de página (por defecto: 1)
• per_page: Elementos por página (por defecto: 25, máx: 100)

Filtrado

GET /tasks?status=open&assignee=user_123&label=bug

Ordenamiento

GET /tasks?sort=created_at&order=desc

Incluir Relaciones

GET /tasks/:id?include=comments,time_entries,attachments

Webhooks

Registra webhooks para recibir actualizaciones en tiempo real:

POST /webhooks
{
  "url": "https://tu-servidor.com/webhook",
  "events": ["task.created", "task.updated"],
  "secret": "tu_secreto"
}

SDKs y Bibliotecas

Oficiales

• JavaScript/TypeScript: npm install @gitscrum/sdk
• Python: pip install gitscrum

OpenAPI Spec

Descarga la especificación OpenAPI:

GET /openapi.json

Mejores Prácticas

Usa Paginación

Nunca asumas que puedes obtener todos los elementos. Siempre pagina.

Maneja Límites de Tasa

Verifica X-RateLimit-Remaining y reduce velocidad cuando esté bajo.

Caché Cuando Sea Posible

Usa encabezados ETag para solicitudes condicionales.

Protege Tus Claves

• Nunca commits claves al control de versiones
• Usa variables de entorno
• Rota claves periódicamente

Cómo Reportar un Problema o Solicitar una Funcionalidad

Si encuentras problemas con la API o necesitas endpoints adicionales, envía comentarios a través de GitScrum Studio. En la Barra Lateral, haz clic en Tickets de Soporte y abre un ticket.