Gerar strings de autenticação (REST API)

Última atualização: 31 de março de 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?