API REST: visión general

Disponibilidad

La API REST y los webhooks están disponibles en el plan Business. Los planes inferiores usan la consola. La página API y extensiones muestra las integraciones listas para usar.

Principios

La API es una API REST en sentido estricto:

• todo el tráfico pasa por HTTPS en el puerto 443;
• las respuestas son JSON;
• las respuestas usan códigos de estado HTTP estándar; una autenticación fallida devuelve 401;
• la autenticación es por token, emitido desde la consola y revocable en cualquier momento;
• cada llamada queda registrada en el registro de auditoría encadenado por hash del espacio.

Los ejemplos siguientes son indicativos: las rutas y los parámetros exactos están en la documentación de referencia de tu espacio de trabajo.

Autenticación

Un token de API se emite en la consola, en la sección API. Trátalo como un secreto: actúa en nombre del espacio de trabajo dentro de su ámbito.

GET /v1/devices
Authorization: Bearer <TU_TOKEN>
Accept: application/json

Nunca pongas un token en código versionado. Usa un almacén de secretos o una variable de entorno.

Recursos expuestos

Las familias de recursos siguen la estructura del producto:

• sesiones: crear una sesión asistida, recuperar el código de 6 dígitos, leer el estado de la sesión;
• dispositivos: listar agentes instalados, estado en línea, grupos;
• auditoría: leer eventos del registro encadenado por hash;
• usuarios: técnicos y roles, en el plan Business.

Todos los recursos están paginados; las respuestas incluyen los identificadores estables para usar en las llamadas siguientes.

Webhooks

Los webhooks (plan Business) envían los eventos a tu infraestructura en lugar de obligarte a consultar la API continuamente:

• sesión terminada;
• dispositivo desatendido conectado o desconectado;
• eventos de auditoría, por ejemplo una transferencia de archivos confirmada.

Un webhook entregado no es una prueba por sí solo: contrasta los eventos sensibles con el registro de auditoría. Apunta los webhooks a un endpoint HTTPS que controles; el endpoint debe ser accesible por el puerto 443.

Casos de uso habituales

• Automatizar el despliegue: consulta la lista de dispositivos después de un despliegue con GPO o Intune para confirmar que todo el parque está en línea. Ver Instalar y desplegar el agente.
• Alimentar una herramienta ITSM: crea una sesión asistida desde tu sistema de tickets y recupera el código para enviárselo al usuario.
• Supervisar: recibe los eventos de sesión por webhook y correlaciónalos con tu propia supervisión.

¿Consola o API?

Usa la API cuando el trabajo es repetitivo o debe integrarse con otro sistema: aprovisionamiento, supervisión, flujos de tickets. Usa la consola para el soporte interactivo. Ambas gestionan el mismo espacio de trabajo, así que una sesión creada por la API aparece en la consola y viceversa.

Ejemplo: crear una sesión asistida

POST /v1/sessions
Authorization: Bearer <TU_TOKEN>
Content-Type: application/json

{ "mode": "attended", "label": "Equipo de facturación" }

La respuesta contiene el identificador de la sesión y el código de 6 dígitos que hay que enviar al usuario. La solicitud y su resultado quedan en el registro de auditoría, como cualquier acción de la consola.

Buenas prácticas

• Guarda los tokens en un almacén de secretos, nunca en el código.
• Lee los eventos del registro en lugar de consultar la API continuamente.
• Prueba los webhooks con un endpoint de prueba antes de producción.
• Revoca de inmediato el token de un técnico que deja el equipo.

Para seguir avanzando

• Modelo de seguridad y cifrado: qué registra la API y cómo.
• Migrar desde ScreenConnect: automatiza el redespliegue de los agentes durante una migración.