Conceitos

A Riversoft® STCP Gemini API age em nome dos operadores do Riversoft Console Portal: cada chamada autenticada usa as permissões do operador para configurar, administrar, supervisionar e consultar o ambiente do Riversoft STCP Gemini e do Riversoft STCP DirectLink. Esta página reúne o que você precisa saber antes de integrar.

A API não transfere arquivos: para isso, use a Riversoft STCP DirectLink API.

URL base e versionamento

https://{host}:{porta}

O {host} e a {porta} são os configurados na seção general do config.json da API (porta de exemplo: 33070). Veja Configuração da API.

Cada grupo de rotas tem a sua versão no caminho, por exemplo /stcpcore/v2, /reports/v2, /disconnect/api/v3 e /auth/api/v1. A versão do produto é informada em GET /info/version.

Métodos de autenticação

Todos os métodos resultam em um token Bearer, usado nas rotas protegidas.

Veja como escolher e usar cada método em Autenticação.

Credenciais nas rotas protegidas

Envie o token no header Authorization:

Authorization: Bearer <access_token>

Sem token, com token inválido ou expirado, a API responde 401, em texto (Unauthorized). Com token válido, mas sem a permissão exigida pela rota, responde 403. As rotas de /info e de login são públicas. Detalhes em Sessão e logout.

Fluxo de uma integração

    flowchart TD
    A[Aplicação] --> B{Método de autenticação}
    B -->|Login local ou LDAP| C["POST /oauth/v2/token"]
    C --> D{2FA habilitada?}
    D -->|Sim| E["POST /oauth/v2/token/mfa/challengeID"]
    D -->|Não| F[Token Bearer]
    E --> F
    B -->|Password grant| G["POST /oauth/token"]
    G --> F
    B -->|SSO| H[Redirecionar ao provedor]
    H --> I[Retorno SAML 2.0 ou OAuth 2.0]
    I --> F
    F --> K{Operação}
    K -->|Configurar| L["/stcpcore/v2"]
    K -->|Administrar| M["/stcpadmin/v2"]
    K -->|Supervisionar| N["/stcpadminsvc/v2"]
    K -->|Consultar| O["/reports/v2"]
    L --> Q["DELETE /disconnect/api/v3/logout"]
    M --> Q
    N --> Q
    O --> Q
  

Modelo REST

Os recursos são expostos por endpoints e manipulados com os métodos HTTP de acordo com a operação.

Recursos

Todos os recursos usados pelo Riversoft Console Portal estão disponíveis para integração. Veja o catálogo de endpoints e a Especificação OpenAPI.

Operadores e permissões

As chamadas são feitas em nome de um operador do Riversoft Console Portal. Toda chamada do operador é registrada e pode ser consultada no relatório de operadores.

As permissões vêm dos grupos do operador. Cada grupo define:

• as permissões sobre cada recurso;
• as relações: instâncias, operadores e usuários que os membros do grupo podem acessar. O valor [0] dá acesso a todos.

Quando o operador pertence a mais de um grupo, as permissões são somadas. O operador stcpadmin tem acesso total, independentemente dos grupos. O token emitido traz as permissões no campo scope, organizadas em quatro grupos de recursos:

A permissão exigida por cada endpoint está indicada na Especificação OpenAPI.

Entidades de configuração

As entidades de configuração e de administração seguem o mesmo envelope: ID, NAME, DESCRIPTION, CONFIG_TXT (a configuração, em JSON), CREATED, MODIFIED e EXTRA_TXT. As entidades de uma instância (usuários, serviços de rede, agendamentos, tipos de arquivo globais e roteamentos) têm também INSTANCE_ID; os tipos de arquivo do usuário, USER_ID.

• Na alteração (PUT), o CONFIG_TXT enviado substitui o gravado por inteiro: consulte a entidade, altere os campos e envie o objeto completo.
• Senhas e segredos voltam mascarados nas consultas. Reenviar o valor mascarado mantém o gravado.
• O operador só vê as entidades relacionadas aos seus grupos.

Veja Estrutura do CONFIG_TXT.

Formatos de dados

Datas: os filtros start e end dos relatórios usam Unix timestamp em milissegundos e são obrigatórios. O campo DATAHORA das respostas usa o formato ISO 8601 (por exemplo, 2025-12-20T19:54:17-03:00).

Respostas e erros

Os erros vêm em JSON, com o tipo da entidade, o erro e a descrição:

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

As rotas de login usam somente error e error_description. Veja Códigos de resposta.

Paginação

Os relatórios retornam os registros em data e, quando há mais resultados, a URI da próxima página em next. Repita a chamada com a URI de next até que ela venha vazia. O parâmetro limit define a quantidade por página: padrão 100, máximo 15000. Os relatórios de auditoria retornam todo o período, sem paginação.