Recursos de gestão
Guia relacionado: Gerenciar recursos. O contrato completo de cada endpoint está na Especificação OpenAPI.
Convenções
| Item | Regra |
|---|---|
| Identificação | As entidades são acessadas pelo ID no caminho: /id/{ID}. |
| Corpo | JSON, com o header Content-Type: application/json exatamente assim, sem charset. |
| Criação | POST no caminho da coleção, com a entidade sem o campo ID. |
| Alteração | PUT no caminho da entidade, com a entidade completa. O CONFIG_TXT enviado substitui o gravado por inteiro. |
| Campos sensíveis | Senhas e segredos voltam mascarados (****) nas consultas. Ao alterar, envie o valor mascarado para manter o valor gravado. |
| Acesso | O operador só vê as entidades relacionadas aos seus grupos. |
Formato das entidades
As entidades de configuração seguem o mesmo envelope:
| Campo | Descrição |
|---|---|
ID | Identificador. Omitido na criação. |
INSTANCE_ID ou USER_ID | Entidade a que pertence (instância ou usuário), quando aplicável. |
NAME | Nome. Obrigatório. |
DESCRIPTION | Descrição. |
CONFIG_TXT | Configuração da entidade, no mesmo formato usado pelo Riversoft Console Portal. |
CREATED, MODIFIED | Datas de criação e da última alteração. |
EXTRA_TXT | Dados adicionais. |
Dica
Para criar uma entidade nova, a forma mais simples é consultar uma existente semelhante, alterar o NAME e os campos necessários e enviá-la sem o ID.
Estrutura do CONFIG_TXT
O CONFIG_TXT é um objeto JSON, dividido em seções. Todas têm a seção Entity, com o tipo da entidade (Name) e a versão da estrutura (Version = 2). Os campos de cada seção estão nos esquemas Cfg* da Especificação OpenAPI.
| Entidade | Esquema | Seções |
|---|---|---|
| Instância | CfgInstance | Authentication (autenticação dos usuários, MFA, políticas de senha e LDAP), Log (banco e filtros de log), Startup (serviço, diretórios, sessões, lock externo e provedores SSO) |
| Usuário | CfgUser | General, Token, Net1 e Net2 (rede principal e alternativa), e uma seção por protocolo: OFTP, SFTP, FTP, S3, AzBlob, OciBlob, GcpBlob, WhatsApp, AS2, WebHook |
| Serviço de rede | CfgService | Service, Net1, e uma seção por tipo: OFTP, SFTP, API, WhatsApp, AS2, WebHook, Monitor |
| Agendamento | CfgSchedule | Schedule |
| Tipo de arquivo (global ou do usuário) | CfgFileType | FileConf |
| Roteamento | CfgRouting | Rules.General (varredura) e Rules.FileMatching[] (regras, com General, Filename, Copy e Backup) |
| Operador | — | Operator, Relations.Groups |
| Grupo | — | Permissions, Relations |
| Cadastro da API | — | Monitor, passwordPolicies, ssoProviders, enable2FA, TLS e SSO |
Cuidados ao alterar:
- O
PUTsubstitui oCONFIG_TXTinteiro. Campos omitidos voltam ao valor vazio ou zero. Consulte a entidade, altere os campos e envie o objeto completo. - Campos desconhecidos são ignorados sem erro. Confira o nome dos campos no esquema.
- Campos sensíveis voltam mascarados. Reenviar o valor mascarado mantém o valor gravado.
Nota
Os esquemas correspondem ao módulo de configuração stcpcfgifacetypes-go v1.3.2, usado pela Riversoft STCP Gemini API 3.10.0.
Valores codificados
Alguns campos do CONFIG_TXT usam códigos. Quando o campo aceita uma combinação, o valor é a soma dos códigos.
| Campo | Valores |
|---|---|
Usuário: General.TransferProtocol | 0 desabilitado, 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 |
Usuário: General.TransferProtocolIn | Protocolos aceitos na conexão de entrada: soma de 2^protocolo. Exemplo: OFTP e SFTP = 2 + 4 = 6 |
Usuário: General.AuthMFAMethod | 0 segue a instância; 128 desabilita o MFA para o usuário |
Usuário: InitMode | Both, Initiator, Responder |
Usuário: Mode | Both, Sender, Receiver |
Usuário: *ProxyType | 0 SOCKS4, 1 SOCKS5, 2 HTTP, 3 HTTPS, 4 FTP |
Usuário: AS2.MDNOptions (soma) | 1 habilitado, 2 assinado, 4 assíncrono, 8 criptografado |
Usuário: SendDocumentOptions e RequiredDocumentOptions (soma) | 1 assinado (multipart), 2 assinado, 4 criptografado, 8 comprimido |
Usuário: AuthMode (AS2 e Webhook) | 0 nenhuma, 1 Basic, 2 Bearer |
Usuário: Net1.WhatsAppDownloadMode | 0 ID do documento na Meta, 1 link da Meta, 2 link seguro sem senha, 3 link seguro com senha |
Serviço: Service.ServiceType | 0 OFTP, 1 API, 2 supervisão (DirectLink), 3 SFTP, 4 supervisão (Gemini), 5 WhatsApp, 6 AS2, 7 Webhook |
Serviço: API.AuthMode (soma) | 1 Basic, 2 Bearer, 4 token exchange (JWT), 8 password grant. 0 aceita todos. O token Bearer é sempre exigido nas rotas que não são de autenticação. |
Agendamento: Schedule.Type (soma) | 1 recepção, 2 transmissão, 4 comando, 8 transmissão otimizada, 128 Riversoft STCP DirectLink |
Agendamento: Schedule.Mode | 0 data, 1 data com intervalo, 2 intervalo |
Tipo de arquivo: FileConf.FileMatch | 0 padrão, 1 prefixo/sufixo, 2 nome do arquivo, 3 expressão regular |
Tipo de arquivo: FileConf.FileDirection | 0 ambos, 1 transmissão desabilitada, 2 recepção desabilitada |
Instância: Authentication.AuthType | 0 sistema operacional, 1 STCP, 2 RSA SecurID, 3 LDAP |
Instância: Authentication.AuthMFAMethod | 0 desabilitado, 1 aplicativo autenticador (TOTP), 2 código por e-mail, 3 código por SMS |
Instância: Authentication.AuthPolicyPswdComplex e cadastro da API: passwordPolicies.complexity (soma) | 1 minúscula, 2 maiúscula, 4 dígito, 8 símbolo (15 = todas) |
Instância: Startup.ExternalLockType | in-memory, filesystem, redis |
Instância: Startup.OSType | LINUX, WINNT, WIN32, MACOS |
Provedor SSO: ssoType | oauth2, saml2, jwt, ldap |
Respostas
| Operação | Resposta 200 |
|---|---|
Consulta (GET) | {"status": 200, "field": "<entidade>", "data": [ ... ]} |
Criação e alteração (POST, PUT) | {"data": "<nome da entidade>", "field": "<entidade>"} |
Exclusão (DELETE) | {"data": "<Entidade> deleted with success", "field": "<entidade>"} |
Os erros seguem o formato descrito em Códigos de resposta.
Configuração (/stcpcore/v2)
| Recurso | Caminho | Permissão |
|---|---|---|
| Instâncias | /instances | stcpcore.instance |
| Instâncias e seus usuários | /instances/members | stcpcore.instance = 15 |
| Usuários | /instances/id/{instanceID}/users | stcpcore.user |
| Serviços de rede | /instances/id/{instanceID}/services | stcpcore.service |
| Agendamentos | /instances/id/{instanceID}/schedules | stcpcore.schedule |
| Tipos de arquivo globais | /instances/id/{instanceID}/ftypesglobal | stcpcore.filetypeglobal |
| Tipos de arquivo do usuário | /instances/id/{instanceID}/users/id/{userID}/filetypes | stcpcore.filetype |
| Roteamentos (Riversoft STCP Gemini Rename) | /instances/id/{instanceID}/routing | stcpcore.routing |
Os tipos de arquivo têm também GET .../check?filename=<nome>, que retorna os tipos cuja expressão regular corresponde ao nome informado. Os roteamentos podem ser consultados pelo nome em GET .../routing/name/{nome}.
Administração (/stcpadmin/v2)
| Recurso | Caminho | Permissão |
|---|---|---|
| Operadores | /operators | stcpadmin.operator |
| Perfil e senha do próprio operador | /operators/me, /operators/me/password | stcpadmin.operator |
| Grupos e permissões | /groups, /groups/id/{groupID}/operators | stcpadmin.group |
| Cadastro da API | /settings | stcpadmin.setting |
| Políticas de senha | /api/policies | stcpadmin.operator = 15 |
| Códigos de erro e evento | /error_events | stcpadmin.error_event |
O cadastro da API corresponde ao API/Supervisão do Riversoft Console Portal. Ele guarda TLS, endereço e porta, ativação do 2FA, políticas de senha, provedores de SSO e os nós de supervisão (instância, nome do nó, credencial, host, porta, TLS e certificado). A API carrega, na inicialização, o cadastro cujo nome é igual ao rest_name do seu config.json.
Supervisão (/stcpadminsvc/v2/supervision/stcpmon)
Os comandos são enviados pela API aos serviços de supervisão do Riversoft STCP Gemini Server e do Riversoft STCP DirectLink cadastrados no cadastro da API. Todos usam POST com o corpo {"Instance": "...", "Node": "...", "Name": "...", "Level": "..."}; sem Node, o comando vai para todos os nós da instância.
| Caminho | Comando | Permissão (stcpadminsvc) |
|---|---|---|
/monitor/nodes | Lista os nós de supervisão habilitados. | mon_console_info |
/instance/info | Informações da instância. | mon_inst_info |
/instance/restart | Reinicia a instância. | mon_inst_restart |
/instance/debug | Altera o nível de debug (Level). | main_set_level |
/instance/console | Mensagens do console. | mon_console_info |
/user/info | Informações dos usuários. | mon_user_info |
/user/start | Inicia uma conexão de saída com o usuário (Name). | mon_user_start_conn |
/user/stop | Cancela a conexão do usuário (Name). | mon_user_canc_conn |
/user/create_folder | Cria a estrutura de diretórios do usuário (Name). | main_user_create_folders |
/schedule/start | Executa a agenda (Name) na hora. | mon_sched_exec |
/service/info | Informações dos serviços de rede. | mon_inst_serv |
/sandbox, /keystore | Lista (GET), envia (POST, conteúdo em Base64) e exclui (DELETE) arquivos da caixa postal ou do keystore. | mon_sandbox_file_management, mon_keystore_file_management |
A resposta traz, em data, a resposta de cada nó: {"Instance": "...", "Nodename": "...", "Data": [ ... ]}.
Manutenção (/stcpadminsvc/v2/supervision/stcpauth)
Todos usam POST com o corpo {"Instance": "...", "Name": "...", "NewPassword": "...", "CurrentPassword": "..."}. Para operadores, Instance não é usado.
| Caminho | Operação |
|---|---|
/reset/user/password, /reset/operator/password | Define uma nova senha, validada contra as políticas de senha. |
/change/user/password, /change/operator/password | Troca a senha, informando a atual em CurrentPassword. |
/reset/user/lock, /reset/operator/lock | Remove o bloqueio por falhas de login. |
/reset/user/hash | Recria o hash de autenticação do usuário. |
/reset/user/2fa, /reset/operator/2fa | Apaga o segredo TOTP; um novo é gerado no próximo login. |