Solução de problemas

Sintoma: uma integração que funcionava na versão 8 passa a receber 400 em /upload, /download/list ou /report.

Causa provável: a chamada envia Authorization: Basic. A partir da versão 9, essas rotas aceitam somente token Bearer.

Solução: obtenha um token em POST /oauth2/token (ou no login) e envie Authorization: Bearer <access_token>. Veja Autenticação na API.

Sintoma: a API retorna 401.

Causa provável: usuário inexistente, senha incorreta, token Bearer expirado ou com assinatura, emissor ou público inválidos.

Solução: confira usuário e senha cadastrados no servidor STCP. Obtenha um novo token em /oauth2/token; ele expira após expires_in segundos.

Sintoma: a troca do JWT do portal de serviços por um token do Riversoft® STCP DirectLink é rejeitada.

Causa provável: a assinatura do JWT não confere com a chave cadastrada para o provedor, o iss ou o aud não correspondem à configuração, o token expirou ou o usuário das claims não existe no servidor STCP.

Solução: verifique se o token foi assinado com a chave privada correspondente à chave cadastrada e se kid e alg coincidem. Confira o identificador enviado em provider (ou no header X-STCPDIRECTLINK-JWT-ISSUER), o relógio dos servidores e o usuário. Veja JWT de confiança.

Sintoma: POST /oauth2/token retorna 400.

Causa provável: o corpo não está no formato application/x-www-form-urlencoded, falta grant_type ou, no token exchange, subject_token_type é diferente de urn:ietf:params:oauth:token-type:jwt.

Solução: envie o formulário com o header Content-Type: application/x-www-form-urlencoded. No password grant: grant_type=password&username=<usuario>&password=<senha>. A resposta traz error e error_description com o motivo.

Sintoma: o token é aceito, mas a chamada retorna 403.

Causa provável: uma regra de acesso bloqueou a operação: conexão do usuário bloqueada, fora da janela de horário, serviço desabilitado, filtro de arquivo, limite de sessões ou host da URL diferente do configurado para a API.

Solução: use exatamente o host informado pelo administrador e peça a ele que verifique as regras do usuário no servidor STCP.

Sintoma: o login, o primeiro acesso ou a recuperação de senha retorna 400, 403 ou 503.

Causa provável: 400 indica que o header CF-Turnstile-Response não foi enviado ou é inválido; 403, que o token foi rejeitado (inválido, expirado ou já utilizado); 503, que o servidor não conseguiu validar o token com a Cloudflare.

Solução: gere um novo token do widget a cada tentativa (ele é de uso único e expira em 300 segundos). Em caso de 503, tente novamente; se persistir, o administrador deve verificar a saída HTTPS do servidor para challenges.cloudflare.com.

Sintoma: GET /auth/firstaccess retorna 403.

Causa provável: o usuário já fez o primeiro acesso.

Solução: use Esqueceu a senha para redefinir a senha.

Sintoma: um arquivo já baixado não aparece em /download/list.

Causa provável: após o download, o arquivo é movido para a área de backup.

Solução: consulte /download/list/backup e baixe novamente pelo linkURL retornado, enquanto a política de retenção permitir.

Sintoma: a lista retorna no máximo 100 arquivos.

Causa provável: a lista é paginada.

Solução: incremente o parâmetro page a partir de 0 até receber uma lista vazia.

Sintoma: o endereço /portal retorna 404 ou o portal não carrega a configuração.

Causa provável: o config.json do portal não foi criado a partir do example-config.json, ou o caminho das páginas estáticas do serviço da API na instância não é o padrão.

Solução: crie o config.json a partir do modelo (veja Configuração do Riversoft STCP DirectLink Portal) e confira, no serviço de rede da API da instância, se o caminho das páginas estáticas é /usr/local/stcpdirectlink/static, sem barra no fim.