Gerar strings de autenticação (API REST)

Última atualização: 7 de outubro de 2026

Alguns endpoints REST permitem realizar operações sensíveis, como colocar ordens ou solicitar o levantamento de ativos digitais. Estes endpoints privados só podem ser chamados através de pedidos encriptados, sendo obrigatório incluir uma string de autenticação (authent) em cada pedido. O authent é calculado a partir das seguintes entradas:

PostData

postData é uma concatenação com «&» no formato = e é específico de cada endpoint REST.

Exemplo

Para operar o endpoint orderbook, escolha o argumento symbol com o valor
fi_xbtusd_180615. O 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 boas práticas e garantir um nível de segurança mais elevado, iremos atualizar o fluxo de autenticação dos nossos endpoints /derivatives/* (v3). (detalhes abaixo)

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


- Antes da atualização: os clientes tinham de fazer hash dos parâmetros da query string antes da codificação URL para geração do Authent, por exemplo, `greeting=hello world`.


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


Retrocompatibilidade e planos futuros:


Por enquanto, esta alteração é retrocompatível. A plataforma aceita ambos os métodos de geração de PostData descritos acima. No entanto, pretendemos descontinuar o método antigo (hash de parâmetros de query string descodificados) para manter os mais elevados padrões de segurança. Avisaremos com antecedência e encorajamos todos os clientes a adotar o novo método o mais brevemente possível, para garantir a continuidade do serviço sem interrupções.

Nonce

O nonce é um parâmetro inteiro em incremento contínuo. Um bom nonce é o tempo do sistema em
milissegundos (em formato string). O nosso sistema tolera nonces fora de ordem durante um breve período. O nonce não é obrigatório.

Exemplo 1415957147987

Muitos problemas de autenticação estão relacionados com um nonce incorreto. A criação de um novo par de chaves de API repõe automaticamente o nonce e resolve estes problemas.

Caminho do endpoint

endpointPath é a extensão de URL do endpoint.

Exemplo /api/v3/orderbook

API Secret

O api_secret é obtido conforme descrito na secção anterior.

Exemplo

rttp4AzwRfYEdQ7R7X8Z/04Y4TZPa97pqCypi3xXxAqftygftnI6H9yGV+O
cUOOJeFtZkr8mVwbAndU3Kz4Q+eG

Com base nestes parâmetros, o authent é calculado da seguinte forma:

  1. 1

    Concatene

    postData

    +

    valor aleatório (nonce)

    +

    endpointPath

  2. 2

    Aplique o hash ao resultado do passo 1 com o algoritmo SHA-256

  3. 3

    Descodifique em Base64 o seu api_secret

  4. 4

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

  5. 5

    Codifique em Base64 o resultado do passo 4

Exemplo

O exemplo seguinte apresenta uma implementação de authent em Java. Para exemplos funcionais completos noutras 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();
}