Migração da v1 para a v2
A partir do Riversoft® STCP DirectLink 9.0.1, a Riversoft STCP DirectLink API atende somente na versão v2, com o prefixo /directlink/v2. A versão v1 não é mais atendida. Adeque as integrações antes da atualização do ambiente.
O que muda
| Mudança na v2 | O que fazer na integração |
|---|---|
Prefixo /directlink/v2 em todas as rotas. | Troque /directlink/v1 por /directlink/v2 nas URLs. |
Upload, listagens, relatório e logout exigem token Bearer, no header Authorization ou no cookie de sessão. Basic é aceito somente em /auth/login. | Obtenha um token e envie Authorization: Bearer <token>. Veja Autenticação. |
O download de arquivo listado (/download/file e /download/file/backup) exige o linkURL e o token Bearer ou o cookie de sessão do mesmo usuário que fez a listagem. | Envie o mesmo token da listagem ao baixar o arquivo. Veja Receber arquivos. |
/auth/token e /oauth2/token são equivalentes e emitem tokens por password grant ou token exchange, conforme os métodos habilitados no ambiente. | Confirme com o administrador os métodos habilitados. Para seguir o OAuth 2.1, prefira o token exchange. Veja Tokens OAuth. |
No token exchange, o provedor do JWT é informado no campo provider ou no header X-STCPDIRECTLINK-JWT-ISSUER. | Informe o provedor em cada pedido de token. |
A sessão do portal e do SSO fica no cookie seguro __Host-dirl_session. O token não é mais entregue na URL. | Use a sessão por cookie ou um token obtido nos endpoints de token. |
Chamadas feitas por um host diferente do configurado são recusadas com 403. | Use o endereço configurado para a API. |
O campo time das respostas usa o formato ISO 8601 (RFC 3339), por exemplo 2026-11-07T14:03:21-03:00. | Ajuste a leitura desse campo. |
/auth/change aceita somente POST; outros métodos recebem 405. | Envie POST com p e z no corpo do formulário, nunca na URL. |
O campo apiver informa v2, por exemplo v2 (9.0.1). | Ajuste validações que conferem a versão. |
O link compartilhado (/download), entregue a terceiros com ou sem PIN, continua funcionando sem token.
Como migrar
Levante as integrações
Identifique os sistemas que chamam a API, as rotas usadas e como cada um se autentica hoje.
Troque o prefixo
Altere a URL base para https://{host}/directlink/v2.
Ajuste a autenticação
Obtenha um token por login, token exchange ou password grant (quando habilitado) e envie-o em todas as rotas protegidas, inclusive no download pelo linkURL.
Ajuste a leitura das respostas
Atualize a leitura dos campos time e apiver.
Teste em homologação
Teste o login, o envio, a listagem e o download, o relatório e o logout antes da atualização do ambiente de produção.
Checklist
- Todas as URLs usam
/directlink/v2. - Todas as rotas protegidas enviam o token Bearer ou usam o cookie de sessão.
- O download pelo
linkURLenvia o token do mesmo usuário da listagem. - O campo
timeé lido no formato ISO 8601. - Os métodos de autenticação usados estão habilitados no ambiente.
- O host usado pelos clientes é o configurado para a API.
Para o procedimento de atualização do servidor, destinado aos administradores, veja Migração da versão 8 para a versão 9.