Conceitos

A Riversoft® STCP DirectLink API age em nome dos usuários de transferência do Riversoft STCP DirectLink: cada chamada autenticada usa a caixa postal do usuário para enviar, receber e compartilhar arquivos. Esta página reúne o que você precisa saber antes de integrar. Para a caixa postal, as regras de transferência e o roteamento, veja os conceitos do Riversoft STCP DirectLink.

URL base e host

Todas as chamadas usam o prefixo de versão /directlink/v2:

https://{host}/directlink/v2

Use exatamente o host configurado para o serviço, informado pelo administrador do ambiente. A API pode recusar a requisição (HTTP 403) quando o host ou a porta enviados pelo cliente não correspondem ao endereço configurado. Por isso, evite acessar o serviço por endereço IP ou por um nome alternativo.

Versionamento

A versão da API faz parte do caminho (v2) e é informada no campo apiver das respostas, junto com a versão do produto (por exemplo, v2 (9.0.1)). Esta documentação descreve a versão v2, disponível a partir do Riversoft STCP DirectLink 9.0.1. A versão v1 não é mais atendida; veja Migração da v1 para a v2.

Métodos de autenticação

A API oferece quatro formas de autenticar um usuário. Todas resultam em uma credencial de sessão usada nas rotas protegidas.

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

Credenciais nas rotas protegidas

As rotas protegidas aceitam a credencial de sessão de duas formas:

Quando os dois são enviados, o header Authorization prevalece. Detalhes em Sessão e logout.

Fluxo de uma integração

    flowchart TD
    A[Cliente] --> B{Método de autenticação}
    B -->|Login local| C[POST /auth/login com Basic]
    C --> D{MFA habilitado?}
    D -->|Sim| E[Validar desafio em /auth/mfa]
    D -->|Não| F[Sessão autenticada]
    E --> F
    B -->|OAuth 2.0| G[POST /auth/token ou /oauth2/token]
    G --> F
    B -->|SSO| H[Redirecionar ao provedor]
    H --> I[Callback OAuth 2.0 ou SAML 2.0]
    I --> F
    F --> K{Operação}
    K -->|Enviar| L[POST /upload]
    K -->|Receber| M[GET /download/list]
    M --> N[GET linkURL retornado]
    K -->|Consultar| O[GET /report]
    L --> Q[POST /auth/logout ou logout SSO]
    N --> Q
    O --> Q
  

Downloads por link compartilhado seguem uma validação própria e não exigem que o destinatário inicie uma sessão. Veja Links compartilhados.

Links seguros

Algumas respostas trazem URLs emitidas pelo serviço, em geral no campo linkURL:

Os links seguros:

• são assinados e vinculados à operação, ao usuário e ao arquivo para os quais foram criados;
• têm prazo de validade definido pelo administrador (por padrão, 24 horas para links de download e 180 segundos para PINs) e podem exigir um PIN;
• deixam de funcionar quando o arquivo não está mais disponível.

Use cada link exatamente como recebido. Não remova, edite nem monte manualmente seus parâmetros, e trate-o como uma credencial.

Regras de acesso

Uma credencial válida não garante que toda operação será autorizada. Cada operação também é validada pelas regras configuradas para o usuário e para o ambiente, por exemplo:

• serviço de upload ou download habilitado para o usuário;
• usuário desbloqueado e autorizado;
• horário ou intervalo de acesso permitido;
• limites de tamanho, tipos de arquivo e filtros de nome;
• limite de sessões simultâneas e disponibilidade do recurso;
• sucesso das etapas de pré-processamento configuradas no ambiente.

Quando uma dessas regras impede a operação, a API responde com erro (geralmente 403). Consulte o administrador do serviço para saber quais regras se aplicam ao seu usuário.

Formatos de dados

Datas e horas: o campo timestamp do health check usa RFC 3339 em UTC; o campo modified das listagens usa Unix time em milissegundos. O formato dos demais campos de data (como time) é definido pelo ambiente.

Envelope de resposta

A maioria das operações responde com um objeto JSON com campos comuns:

{
  "status": 0,
  "description": "<descrição retornada pela API>",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "time": "<data e hora>"
}

Cada operação acrescenta seus próprios campos. Os endpoints de token seguem o formato OAuth 2.0 e não usam esse envelope. Veja Modelos de dados.

O formato do corpo de erro varia entre os endpoints: trate primeiro o status HTTP e, quando houver, use a descrição retornada. Veja Códigos e eventos.