Conceptos

Riversoft® STCP Gemini API actúa en nombre de los operadores del Riversoft Console Portal: cada llamada autenticada usa los permisos del operador para configurar, administrar, supervisar y consultar el entorno de Riversoft STCP Gemini y de Riversoft STCP DirectLink. Esta página reúne lo que necesita saber antes de integrar.

La API no transfiere archivos: para eso, use la Riversoft STCP DirectLink API.

URL base y control de versiones

https://{host}:{puerto}

El {host} y el {puerto} son los configurados en la sección general del config.json de la API (puerto de ejemplo: 33070). Vea Configuración de la API.

Cada grupo de rutas tiene su versión en la ruta, por ejemplo /stcpcore/v2, /reports/v2, /disconnect/api/v3 y /auth/api/v1. La versión del producto se informa en GET /info/version.

Métodos de autenticación

Todos los métodos resultan en un token Bearer, usado en las rutas protegidas.

Vea cómo elegir y usar cada método en Autenticación.

Credenciales en las rutas protegidas

Envíe el token en el header Authorization:

Authorization: Bearer <access_token>

Sin token, o con un token no válido o expirado, la API responde 401, en texto (Unauthorized). Con un token válido, pero sin el permiso exigido por la ruta, responde 403. Las rutas de /info y de inicio de sesión son públicas. Detalles en Sesión y logout.

Flujo de una integración

    flowchart TD
    A[Aplicación] --> B{Método de autenticación}
    B -->|Inicio de sesión local o LDAP| C["POST /oauth/v2/token"]
    C --> D{¿2FA habilitado?}
    D -->|Sí| E["POST /oauth/v2/token/mfa/challengeID"]
    D -->|No| F[Token Bearer]
    E --> F
    B -->|Password grant| G["POST /oauth/token"]
    G --> F
    B -->|SSO| H[Redirigir al proveedor]
    H --> I[Retorno SAML 2.0 u OAuth 2.0]
    I --> F
    F --> K{Operación}
    K -->|Configurar| L["/stcpcore/v2"]
    K -->|Administrar| M["/stcpadmin/v2"]
    K -->|Supervisar| N["/stcpadminsvc/v2"]
    K -->|Consultar| O["/reports/v2"]
    L --> Q["DELETE /disconnect/api/v3/logout"]
    M --> Q
    N --> Q
    O --> Q
  

Modelo REST

Los recursos se exponen mediante endpoints y se manipulan con los métodos HTTP según la operación.

Recursos

Todos los recursos que usa el Riversoft Console Portal están disponibles para integración. Vea el catálogo de endpoints y la Especificación OpenAPI.

Operadores y permisos

Las llamadas se hacen en nombre de un operador del Riversoft Console Portal. Toda llamada del operador se registra y puede consultarse en el informe de operadores.

Los permisos vienen de los grupos del operador. Cada grupo define:

• los permisos sobre cada recurso;
• las relaciones: instancias, operadores y usuarios a los que los miembros del grupo pueden acceder. El valor [0] da acceso a todos.

Cuando el operador pertenece a más de un grupo, los permisos se suman. El operador stcpadmin tiene acceso total, independientemente de los grupos. El token emitido trae los permisos en el campo scope, organizados en cuatro grupos de recursos:

El permiso exigido por cada endpoint está indicado en la Especificación OpenAPI.

Entidades de configuración

Las entidades de configuración y de administración siguen el mismo envoltorio: ID, NAME, DESCRIPTION, CONFIG_TXT (la configuración, en JSON), CREATED, MODIFIED y EXTRA_TXT. Las entidades de una instancia (usuarios, servicios de red, agendas, tipos de archivo globales y enrutamientos) también tienen INSTANCE_ID; los tipos de archivo del usuario, USER_ID.

• En la modificación (PUT), el CONFIG_TXT enviado sustituye por completo al guardado: consulte la entidad, modifique los campos y envíe el objeto completo.
• Las contraseñas y los secretos vuelven enmascarados en las consultas. Reenviar el valor enmascarado mantiene el guardado.
• El operador solo ve las entidades relacionadas con sus grupos.

Vea Estructura del CONFIG_TXT.

Formatos de datos

Fechas: los filtros start y end de los informes usan Unix timestamp en milisegundos y son obligatorios. El campo DATAHORA de las respuestas usa el formato ISO 8601 (por ejemplo, 2025-12-20T19:54:17-03:00).

Respuestas y errores

Los errores vienen en JSON, con el tipo de la entidad, el error y la descripción:

{
  "field": "instance",
  "error": "instance error",
  "error_description": "NAME is required"
}

Las rutas de inicio de sesión usan solo error y error_description. Vea Códigos de respuesta.

Paginación

Los informes devuelven los registros en data y, cuando hay más resultados, la URI de la página siguiente en next. Repita la llamada con la URI de next hasta que venga vacía. El parámetro limit define la cantidad por página: predeterminado 100, máximo 15000. Los informes de auditoría devuelven todo el período, sin paginación.