Autenticación y firma

URL base y formato

• Endpoint: https://api.cobrex.com
• Formato: peticiones y respuestas en JSON (Content-Type: application/json cuando hay cuerpo).
• Claves: se crean en ajustes del panel.

Códigos HTTP

Rango	Significado
200	Éxito (en la documentación Cobrex suele ser 200).
4xx	Error del cliente: firma, parámetros, permisos, no encontrado.
5xx	Error del servidor; reintente más tarde si aplica.

Cabeceras obligatorias

Toda petición protegida debe incluir:

1. x-uid o x-mid

• x-uid — id de usuario (u-…). Para operaciones a nivel de cuenta.
• x-mid — id de comerciante (m-…). Para el contexto comerciante (p. ej. retiro desde la cuenta vinculada).

Envíe exactamente una de las dos, según el flujo.

2. x-timestamp

Hora actual en segundos enteros desde 1970-01-01 UTC (Unix). Reduce riesgo de replay; el servidor puede rechazar marcas antiguas o demasiado futuras.

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

No use Date.now() puro — son milisegundos y no coincidirá con la firma esperada.

3. x-signature

HMAC-SHA256 en hex de la cadena canónica (abajo), con su secreto API.

Cómo construir la cadena a firmar (paso a paso)

1. URL completa de la petición — exactamente como llama a la API:
   https + :// + host + ruta + query (si existe).
   El orden de los parámetros en la query debe coincidir con la petición.
2. Salto de línea LF \n.
3. Solo segundos — el mismo valor que envía en x-timestamp.
4. Si hay cuerpo (p. ej. JSON en POST):
   • \n
   • Cuerpo en bruto — los mismos bytes que envía (tras JSON.stringify o equivalente).
     Espacios y orden de claves deben coincidir con el cuerpo real.

Si no hay cuerpo (típico GET): deténgase tras el paso 3. No añada un \n extra por “cuerpo vacío”.

Ejemplo POST

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

Ejemplo GET

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

Firma hex en código

1. Construya canonicalString como arriba.
2. HMAC-SHA256 sobre canonicalString con el secreto API.
3. Codifique el digest en hex (minúsculas es habitual).

Node.js (crypto):

const crypto = require('crypto');

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

Errores frecuentes

Problema	Efecto
Milisegundos en x-timestamp	La firma no coincide.
Otro orden/espaciado en JSON	Otro cuerpo → otra firma. Serialice una vez y reutilice.
URL sin query u orden distinto	La cadena canónica difiere del servidor.
\n de más sin cuerpo	La firma no coincide.

---

Webhooks: verificar peticiones entrantes

Cobrex llama a su URL cuando cambia el estado de un pago o retiro. El cuerpo es JSON (objeto de pago u objeto de retiro).

Opción A — lista blanca de IP

Solo acepte tráfico desde las IP de Cobrex:

46.166.162.83

(La infra puede cambiar — confirme la lista en soporte antes de producción.)

Opción B — cabecera x-signature

1. Lea el cuerpo HTTP en bruto como texto/búfer antes de JSON.parse.

2. Parse JSON a data para la lógica de negocio.

3. Firma esperada según reglas Cobrex del webhook; a menudo es más fiable el HMAC sobre la cadena del cuerpo en bruto:

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

4. Compare expected con x-signature con comparación en tiempo constante.

---

Siguiente: cuentas y saldos, pagos, retiros.