Cómo usar la API REST de Xcellerate OPS con claves API personales

Xcellerate OPS tiene una API REST documentada (v1). Con ella conectas tus propias herramientas, scripts o plataformas de automatización a tickets, empresas, contactos, oportunidades, proyectos, registros de tiempo, activos y más. Cada usuario crea sus propias claves API desde su perfil, y una clave puede hacer exactamente lo que ese usuario puede hacer en la aplicación, nada más. Esta guía es para administradores técnicos de MSP y empresas de servicios.

TL;DR

• Crea una clave en tu perfil, en API keys, y copia el token enseguida: solo se muestra una vez.
• Envía dos cabeceras en cada solicitud: Authorization: Bearer <token> y X-Tenant-Id.
• Una clave hereda los permisos de tu usuario. El límite por defecto es de 120 solicitudes por minuto y clave.

Antes de empezar

• Cualquier miembro del personal puede crear claves para sí mismo. No necesitas el rol de administrador.
• Lo que puede hacer una clave coincide uno a uno con los permisos de tu equipo. Lo que está bloqueado en la aplicación también lo está en la API.
• Necesitas un cliente HTTP que pueda enviar cabeceras: un script, una plataforma de automatización o tu propia aplicación.
• Puedes tener hasta 20 claves activas por usuario.

Nota: la sección de claves API solo está en inglés en la aplicación, por eso las etiquetas de abajo están en inglés.

Crear y usar una clave API

Paso 1: Abre tus claves API

Ve a tu perfil y abre la sección API keys (Claves API).

Paso 2: Crea la clave

Dale a la clave un nombre que indique para qué sirve. Elige si solo puede leer o también escribir, y fija, si quieres, una fecha de caducidad en el futuro. Las claves son de solo lectura, salvo que las crees con acceso de escritura. Si solo necesitas leer datos, déjala en solo lectura.

Paso 3: Copia el token

Tras crearla, OPS muestra «Copy your new API key now — it will not be shown again.» Copia el token de inmediato y guárdalo en un lugar seguro. Los tokens empiezan por xok_. Si lo pierdes, crea una clave nueva.

Paso 4: Copia el ID de tu espacio de trabajo

La misma sección muestra el ID de tu espacio de trabajo (tenant id). Cópialo con el botón Copy (Copiar). Lo necesitas en cada solicitud.

Paso 5: Haz una primera llamada

Prueba tu clave con una solicitud sencilla a /api/v1/me, con las dos cabeceras:

GET /api/v1/me
Authorization: Bearer <token>
X-Tenant-Id: <workspace id>

El enlace API documentation ↗ (documentación de la API) de la sección abre la documentación interactiva. Comprueba allí la dirección base correcta y los endpoints disponibles.

Paso 6: Revoca las claves que ya no uses

Revocas una clave desde la misma lista. Cada clave muestra cuándo se usó por última vez, así detectas fácilmente las que ya nadie necesita.

Qué ocurre después de conectar

• Formato: JSON en solicitudes y respuestas. Las listas se paginan con cursor.
• Cobertura: entre otros, empresas, contactos, interacciones de CRM, campos personalizados, tickets y programaciones de tickets, proyectos con planificación y finanzas, registros de tiempo, gastos, ausencias, tiempo de trabajo, activos y CMDB, software, servicios, cambios, problemas, incidentes graves, versiones, base de conocimiento, oportunidades, tarifas, facturas recurrentes, informes, informes SLA y XLA, llamadas y grabaciones, y el registro de acciones de IA. La lista completa está en la documentación de la API.
• Portal de clientes: los clientes que usan tu portal de clientes pueden crear allí sus propias claves. Esas claves solo ven los datos del propio cliente.

Para saber cómo protege OPS el acceso, consulta seguridad y control de acceso. Todas las conexiones aparecen en integraciones europeas y seguridad.

Conviene saber

• Límite de uso: por defecto 120 solicitudes por minuto y clave. RMM Labs puede ampliarlo para un espacio de trabajo si lo pides. Cada respuesta incluye las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining.
• Autenticaciones fallidas: los intentos fallidos repetidos desde la misma dirección se bloquean temporalmente.
• Las claves pertenecen a una persona. Desactivar a un usuario revoca sus claves y lo bloquea. Las integraciones que funcionan con esas claves dejan de funcionar, así que tenlo en cuenta cuando alguien se va.
• Los ajustes personales, como las preferencias de sincronización de calendario, no están disponibles en la API.

Solución de problemas

• 401 unauthenticated «Invalid API credentials.» El token es incorrecto, ha caducado o está revocado, falta el X-Tenant-Id o es incorrecto, el espacio de trabajo está suspendido o el usuario está desactivado. Todos estos casos dan a propósito la misma respuesta.
• 429 rate_limited «Too many requests.» Espera los segundos que indica la cabecera Retry-After.
• 429 «Too many failed authentication attempts.» Tu dirección IP está bloqueada temporalmente tras varios fallos.
• «You have reached the maximum number of API keys.» Tienes 20 claves activas. Revoca una primero.

Empieza

¿Quieres conectar OPS con tus propios scripts y herramientas? Empieza gratis y crea tu primera clave API en tu perfil.