Gerar strings de autenticação (REST API)

Última atualização: 31/03/2025

Alguns endpoints REST permitem realizar operações sensíveis, como fazer pedidos ou solicitar um levantamento de ativos digitais. Estes endpoints privados só podem, portanto, ser chamados através de pedidos encriptados e uma string de autenticação (authent) deve ser incluída em cada um desses pedidos. A autenticação é calculada a partir dos seguintes dados:

PostData

postData é uma concatenação "&" na forma <argumento>=<valor> e é específica para cada endpoint REST.

Exemplo

Para operar o endpoint orderbook, escolha o argumento símbolo com o valor
fi_xbtusd_180615. postData é então dado por symbol=fi_xbtusd_180615.

Atualização do Fluxo de Autenticação para endpoints v3: A partir de 20 de fevereiro de 2024, para alinhar com as melhores práticas e garantir um padrão de segurança mais elevado, vamos atualizar o fluxo de autenticação para os nossos endpoints /derivatives/* (v3). (detalhes abaixo)

Alterações na Geração de PostData:


- Antes do lançamento: Os utilizadores eram obrigados a fazer hash dos parâmetros da string de consulta antes da codificação URL para a geração de Authent, por exemplo, `greeting=hello world`.


- Após o lançamento: O processo de autenticação exigirá agora o hashing do componente URI completo e codificado por URL, tal como aparece no pedido, por exemplo, `greeting=hello%20world`. Este método aumenta a segurança e alinha-se com as melhores práticas.
Esta atualização é particularmente relevante para o endpoint v3 batchorder, que aceita um corpo JSON nos seus parâmetros de consulta.


Compatibilidade Retroativa e Planos Futuros:


Por enquanto, esta alteração é retrocompatível. A plataforma aceitará ambos os métodos de geração de PostData descritos acima. No entanto, pretendemos descontinuar o método antigo (hashing de parâmetros de string de consulta descodificados) no futuro para manter os mais altos padrões de segurança. Forneceremos um aviso prévio suficiente antes desta alteração e encorajamos vivamente todos os utilizadores a fazer a transição para o novo método o mais rapidamente possível para garantir a continuidade ininterrupta do serviço.

Nonce

nonce é um parâmetro inteiro que incrementa continuamente. Um bom nonce é a hora do seu sistema em
milissegundos (em formato de string). O nosso sistema tolera nonces fora de ordem por um breve período de tempo. Nonce não é obrigatório.

Exemplo 1415957147987

Muitos problemas de autenticação estão relacionados com um nonce incorreto. Um novo par de chaves API irá automaticamente repor o nonce e resolver estes problemas.

Caminho do Endpoint

endpointPath Esta é a extensão URL do endpoint.

Exemplo /api/v3/orderbook

Chave Secreta da API

A api_secret é obtida conforme descrito na secção anterior.

Exemplo

rttp4AzwRfYEdQ7R7X8Z/04Y4TZPa97pqCypi3xXxAqftygftnI6H9yGV+O
cUOOJeFtZkr8mVwbAndU3Kz4Q+eG

Com base nestas entradas, o authent precisa de ser calculado da seguinte forma:

  1. 1

    Concatenar

    postData

    +

    nonce

    +

    endpointPath

  2. 2

    Faça o hash do resultado do passo 1 com o algoritmo SHA-256

  3. 3

    Descodifique em Base64 a sua api_secret

  4. 4

    Utilize o resultado do passo 3 para fazer o hash do resultado do passo 2 com o algoritmo HMAC-SHA-512

  5. 5

    Codifique em Base64 o resultado do passo 4

Exemplo

O seguinte mostra uma implementação de authent em Java. Para exemplos de trabalho completos em diferentes linguagens de programação, consulte a Secção Recursos Adicionais. public static String getAuthent(String postData, String nonce, String endpointPath, String secretKeyBase64)
{
Mac mac512;
MessageDigest sha256;
try {
SecretKey secretKey = new SecretKeySpec 
(Base64.decode(secretKeyBase64.getBytes()), HMAC_SHA_512);
mac512 = Mac.getInstance(HMAC_SHA_512);
mac512.init(secretKey);
sha256 = MessageDigest.getInstance("SHA-256");
} catch (IOException e) {
...
} catch (InvalidKeyException e) {
...
} catch (NoSuchAlgorithmException e) {
...
} sha256.update(postData.getBytes());
sha256.update(nonce.getBytes());
sha256.update(endpointPath.getBytes());
mac512.update(sha256.digest());
return Base64.encodeBytes(mac512.doFinal()).trim();
}

Precisa de mais ajuda?