Recursos de gestión
Guía relacionada: Gestionar recursos. El contrato completo de cada endpoint está en la Especificación OpenAPI.
Convenciones
| Elemento | Regla |
|---|---|
| Identificación | Las entidades se acceden por el ID en la ruta: /id/{ID}. |
| Cuerpo | JSON, con el header Content-Type: application/json exactamente así, sin charset. |
| Creación | POST en la ruta de la colección, con la entidad sin el campo ID. |
| Modificación | PUT en la ruta de la entidad, con la entidad completa. El CONFIG_TXT enviado sustituye por completo al guardado. |
| Campos sensibles | Las contraseñas y los secretos se devuelven enmascarados (****). Al modificar, envíe el valor enmascarado para mantener el valor guardado. |
| Acceso | El operador solo ve las entidades relacionadas con sus grupos. |
Formato de las entidades
Las entidades de configuración siguen el mismo formato:
| Campo | Descripción |
|---|---|
ID | Identificador. Se omite en la creación. |
INSTANCE_ID o USER_ID | Entidad a la que pertenece (instancia o usuario), cuando corresponde. |
NAME | Nombre. Obligatorio. |
DESCRIPTION | Descripción. |
CONFIG_TXT | Configuración de la entidad, en el mismo formato que usa el Riversoft Console Portal. |
CREATED, MODIFIED | Fechas de creación y de la última modificación. |
EXTRA_TXT | Datos adicionales. |
Consejo
La forma más simple de crear una entidad nueva es consultar una existente similar, cambiar el NAME y los campos necesarios y enviarla sin el ID.
Estructura del CONFIG_TXT
El CONFIG_TXT es un objeto JSON, dividido en secciones. Todas tienen la sección Entity, con el tipo de la entidad (Name) y la versión de la estructura (Version = 2). Los campos de cada sección están en los esquemas Cfg* de la Especificación OpenAPI.
| Entidad | Esquema | Secciones |
|---|---|---|
| Instancia | CfgInstance | Authentication (autenticación de los usuarios, MFA, políticas de contraseña y LDAP), Log (base y filtros de log), Startup (servicio, directorios, sesiones, lock externo y proveedores SSO) |
| Usuario | CfgUser | General, Token, Net1 y Net2 (red principal y alternativa), y una sección por protocolo: OFTP, SFTP, FTP, S3, AzBlob, OciBlob, GcpBlob, WhatsApp, AS2, WebHook |
| Servicio de red | CfgService | Service, Net1, y una sección por tipo: OFTP, SFTP, API, WhatsApp, AS2, WebHook, Monitor |
| Agenda | CfgSchedule | Schedule |
| Tipo de archivo (global o del usuario) | CfgFileType | FileConf |
| Enrutamiento | CfgRouting | Rules.General (exploración) y Rules.FileMatching[] (reglas, con General, Filename, Copy y Backup) |
| Operador | — | Operator, Relations.Groups |
| Grupo | — | Permissions, Relations |
| Registro de la API | — | Monitor, passwordPolicies, ssoProviders, enable2FA, TLS y SSO |
Cuidados al modificar:
- El
PUTsustituye elCONFIG_TXTcompleto. Los campos omitidos vuelven al valor vacío o cero. Consulte la entidad, modifique los campos y envíe el objeto completo. - Los campos desconocidos se ignoran sin error. Verifique el nombre de los campos en el esquema.
- Los campos sensibles vuelven enmascarados. Reenviar el valor enmascarado mantiene el valor guardado.
Nota
Los esquemas corresponden al módulo de configuración stcpcfgifacetypes-go v1.3.2, usado por Riversoft STCP Gemini API 3.10.0.
Valores codificados
Algunos campos del CONFIG_TXT usan códigos. Cuando el campo acepta una combinación, el valor es la suma de los códigos.
| Campo | Valores |
|---|---|
Usuario: General.TransferProtocol | 0 deshabilitado, 1 OFTP, 2 SFTP, 4 Amazon S3, 5 Azure Blob Storage, 6 OCI Object Storage, 7 Google Cloud Storage, 8 WhatsApp, 9 FTP, 10 AS2, 11 Webhook |
Usuario: General.TransferProtocolIn | Protocolos aceptados en la conexión de entrada: suma de 2^protocolo. Ejemplo: OFTP y SFTP = 2 + 4 = 6 |
Usuario: General.AuthMFAMethod | 0 sigue la instancia; 128 deshabilita el MFA para el usuario |
Usuario: InitMode | Both, Initiator, Responder |
Usuario: Mode | Both, Sender, Receiver |
Usuario: *ProxyType | 0 SOCKS4, 1 SOCKS5, 2 HTTP, 3 HTTPS, 4 FTP |
Usuario: AS2.MDNOptions (suma) | 1 habilitado, 2 firmado, 4 asíncrono, 8 cifrado |
Usuario: SendDocumentOptions y RequiredDocumentOptions (suma) | 1 firmado (multipart), 2 firmado, 4 cifrado, 8 comprimido |
Usuario: AuthMode (AS2 y Webhook) | 0 ninguna, 1 Basic, 2 Bearer |
Usuario: Net1.WhatsAppDownloadMode | 0 ID del documento en Meta, 1 link de Meta, 2 link seguro sin contraseña, 3 link seguro con contraseña |
Servicio: Service.ServiceType | 0 OFTP, 1 API, 2 supervisión (DirectLink), 3 SFTP, 4 supervisión (Gemini), 5 WhatsApp, 6 AS2, 7 Webhook |
Servicio: API.AuthMode (suma) | 1 Basic, 2 Bearer, 4 token exchange (JWT), 8 password grant. 0 acepta todos. El token Bearer siempre se exige en las rutas que no son de autenticación. |
Agenda: Schedule.Type (suma) | 1 recepción, 2 transmisión, 4 comando, 8 transmisión optimizada, 128 Riversoft STCP DirectLink |
Agenda: Schedule.Mode | 0 fecha, 1 fecha con intervalo, 2 intervalo |
Tipo de archivo: FileConf.FileMatch | 0 predeterminado, 1 prefijo/sufijo, 2 nombre del archivo, 3 expresión regular |
Tipo de archivo: FileConf.FileDirection | 0 ambos, 1 transmisión deshabilitada, 2 recepción deshabilitada |
Instancia: Authentication.AuthType | 0 sistema operativo, 1 STCP, 2 RSA SecurID, 3 LDAP |
Instancia: Authentication.AuthMFAMethod | 0 deshabilitado, 1 aplicación autenticadora (TOTP), 2 código por correo electrónico, 3 código por SMS |
Instancia: Authentication.AuthPolicyPswdComplex y registro de la API: passwordPolicies.complexity (suma) | 1 minúscula, 2 mayúscula, 4 dígito, 8 símbolo (15 = todas) |
Instancia: Startup.ExternalLockType | in-memory, filesystem, redis |
Instancia: Startup.OSType | LINUX, WINNT, WIN32, MACOS |
Proveedor SSO: ssoType | oauth2, saml2, jwt, ldap |
Respuestas
| Operación | Respuesta 200 |
|---|---|
Consulta (GET) | {"status": 200, "field": "<entidad>", "data": [ ... ]} |
Creación y modificación (POST, PUT) | {"data": "<nombre de la entidad>", "field": "<entidad>"} |
Eliminación (DELETE) | {"data": "<Entidad> deleted with success", "field": "<entidad>"} |
Los errores siguen el formato descrito en Códigos de respuesta.
Configuración (/stcpcore/v2)
| Recurso | Ruta | Permiso |
|---|---|---|
| Instancias | /instances | stcpcore.instance |
| Instancias y sus usuarios | /instances/members | stcpcore.instance = 15 |
| Usuarios | /instances/id/{instanceID}/users | stcpcore.user |
| Servicios de red | /instances/id/{instanceID}/services | stcpcore.service |
| Agendamientos | /instances/id/{instanceID}/schedules | stcpcore.schedule |
| Tipos de archivo globales | /instances/id/{instanceID}/ftypesglobal | stcpcore.filetypeglobal |
| Tipos de archivo del usuario | /instances/id/{instanceID}/users/id/{userID}/filetypes | stcpcore.filetype |
| Enrutamientos (Riversoft STCP Gemini Rename) | /instances/id/{instanceID}/routing | stcpcore.routing |
Los tipos de archivo también tienen GET .../check?filename=<nombre>, que devuelve los tipos cuya expresión regular corresponde al nombre indicado. Los enrutamientos pueden consultarse por nombre en GET .../routing/name/{nombre}.
Administración (/stcpadmin/v2)
| Recurso | Ruta | Permiso |
|---|---|---|
| Operadores | /operators | stcpadmin.operator |
| Perfil y contraseña del propio operador | /operators/me, /operators/me/password | stcpadmin.operator |
| Grupos y permisos | /groups, /groups/id/{groupID}/operators | stcpadmin.group |
| Registro de la API | /settings | stcpadmin.setting |
| Políticas de contraseña | /api/policies | stcpadmin.operator = 15 |
| Códigos de error y evento | /error_events | stcpadmin.error_event |
El registro de la API corresponde a API/Supervisión del Riversoft Console Portal. Guarda TLS, dirección y puerto, habilitación del 2FA, políticas de contraseña, proveedores de SSO y los nodos de supervisión (instancia, nombre del nodo, credencial, host, puerto, TLS y certificado). Al iniciar, la API carga el registro cuyo nombre es igual al rest_name de su config.json.
Supervisión (/stcpadminsvc/v2/supervision/stcpmon)
La API envía los comandos a los servicios de supervisión de Riversoft STCP Gemini Server y Riversoft STCP DirectLink registrados en el registro de la API. Todos usan POST con el cuerpo {"Instance": "...", "Node": "...", "Name": "...", "Level": "..."}; sin Node, el comando va a todos los nodos de la instancia.
| Ruta | Comando | Permiso (stcpadminsvc) |
|---|---|---|
/monitor/nodes | Lista los nodos de supervisión habilitados. | mon_console_info |
/instance/info | Información de la instancia. | mon_inst_info |
/instance/restart | Reinicia la instancia. | mon_inst_restart |
/instance/debug | Cambia el nivel de debug (Level). | main_set_level |
/instance/console | Mensajes de la consola. | mon_console_info |
/user/info | Información de los usuarios. | mon_user_info |
/user/start | Inicia una conexión de salida con el usuario (Name). | mon_user_start_conn |
/user/stop | Cancela la conexión del usuario (Name). | mon_user_canc_conn |
/user/create_folder | Crea la estructura de directorios del usuario (Name). | main_user_create_folders |
/schedule/start | Ejecuta la agenda (Name) en el momento. | mon_sched_exec |
/service/info | Información de los servicios de red. | mon_inst_serv |
/sandbox, /keystore | Lista (GET), envía (POST, contenido en Base64) y elimina (DELETE) archivos del buzón o del keystore. | mon_sandbox_file_management, mon_keystore_file_management |
La respuesta trae, en data, la respuesta de cada nodo: {"Instance": "...", "Nodename": "...", "Data": [ ... ]}.
Mantenimiento (/stcpadminsvc/v2/supervision/stcpauth)
Todos usan POST con el cuerpo {"Instance": "...", "Name": "...", "NewPassword": "...", "CurrentPassword": "..."}. Para operadores, Instance no se usa.
| Ruta | Operación |
|---|---|
/reset/user/password, /reset/operator/password | Define una nueva contraseña, validada contra las políticas de contraseña. |
/change/user/password, /change/operator/password | Cambia la contraseña, indicando la actual en CurrentPassword. |
/reset/user/lock, /reset/operator/lock | Elimina el bloqueo por fallas de inicio de sesión. |
/reset/user/hash | Recrea el hash de autenticación del usuario. |
/reset/user/2fa, /reset/operator/2fa | Elimina el secreto TOTP; se genera uno nuevo en el próximo inicio de sesión. |