Autenticação e assinatura

URL base e formato

• Endpoint: https://api.cobrex.com
• Formato: pedidos e respostas em JSON (Content-Type: application/json quando há corpo).
• Chaves: criadas nas definições do painel.

Códigos HTTP

Intervalo	Significado
200	Sucesso (na documentação Cobrex costuma ser 200).
4xx	Erro do cliente: assinatura, parâmetros, permissões, não encontrado.
5xx	Erro do servidor; reintente mais tarde se fizer sentido.

Cabeçalhos obrigatórios

Cada pedido protegido deve incluir:

1. x-uid ou x-mid

• x-uid — id de utilizador (u-…). Operações ao nível da conta.
• x-mid — id de comerciante (m-…). Contexto comerciante (p. ex. saque da conta vinculada).

Envie apenas um dos dois, conforme o fluxo.

2. x-timestamp

Hora atual em segundos inteiros desde 1970-01-01 UTC (Unix). Reduz risco de replay; o servidor pode rejeitar marcas antigas ou muito futuras.

const timestampSec = Math.floor(Date.now() / 1000);

Não use só Date.now() — são milissegundos e não batem com a assinatura esperada.

3. x-signature

HMAC-SHA256 em hex da cadeia canónica (abaixo), com o seu segredo API.

Montar a cadeia a assinar (passo a passo)

1. URL completa do pedido — como chama mesmo a API:
   https + :// + host + caminho + query (se houver).
   A ordem dos parâmetros na query deve coincidir com o pedido.
2. Nova linha LF \n.
3. Apenas segundos — o mesmo valor que envia em x-timestamp.
4. Se houver corpo (p. ex. JSON em POST):
   • \n
   • Corpo em bruto — os mesmos bytes enviados (após JSON.stringify).
     Espaços e ordem das chaves devem coincidir.

Se não houver corpo (GET típico): pare após o passo 3. Não adicione \n extra por “corpo vazio”.

Exemplo POST

https://api.cobrex.com/wallet
1752675847
{"asset":["USDT","TRX"],"network":"TRON","client":"test1","callback":"https://api.cobrex.com/webhook"}

Exemplo GET

https://api.cobrex.com/payment/p-1a9a67a1-46ce-11f1-8b35-7cc255316480
1752675847

Assinatura hex no código

1. Monte canonicalString como acima.
2. HMAC-SHA256 sobre canonicalString com o segredo API.
3. Codifique o digest em hex (minúsculas é comum).

Node.js (crypto):

const crypto = require('crypto');

function cobrexRequestSignature(canonicalString, apiSecret) {
  return crypto.createHmac('sha256', apiSecret).update(canonicalString).digest('hex');
}

Erros comuns

Problema	Efeito
Milissegundos em x-timestamp	Assinatura não coincide.
Ordem/espaçamento JSON diferente	Corpo diferente → assinatura diferente.
URL sem query ou ordem errada	Cadeia canónica diferente do servidor.
\n extra sem corpo	Assinatura não coincide.

---

Webhooks: verificar pedidos recebidos

A Cobrex chama o seu URL quando muda o estado de um pagamento ou saque. O corpo é JSON (objeto de pagamento ou objeto de saque).

Opção A — lista de IPs

Aceite apenas IPs Cobrex:

46.166.162.83

(A infra pode mudar — confirme a lista com o suporte antes de produção.)

Opção B — cabeçalho x-signature

1. Guarde o corpo HTTP em bruto como texto/buffer antes de JSON.parse.

2. Faça parse para data para a lógica de negócio.

3. Muitas vezes é mais estável calcular HMAC sobre a cadeia do corpo em bruto:

   const crypto = require('crypto');
   const expected = crypto.createHmac('sha256', apiSecret).update(rawBodyString).digest('hex');

4. Compare expected com x-signature com comparação em tempo constante.

---

Seguinte: contas e saldos, pagamentos, saques.