2. Firma de peticiones

Firma de Peticiones con HMAC

Para garantizar la seguridad y autenticidad de las solicitudes a nuestra API, utilizamos HMAC (Hash-based Message Authentication Code) en conjunto con un private key que le será proporcionado.

Código sugerido

Recomendamos utilizar algo parecido a este código para guiarse en la firma de peticiones

const crypto = require("crypto");

const privateKey = process.env.PRIVATE_KEY;

const signRequest = ({ apiPath, body, params }) => {
  const nonce = Date.now().toString();
  let message = "";

  if (body) {
    message = `${JSON.stringify(body)}${nonce}`;
  } else if (apiPath && params) {
    const stringParams = Object.keys(params).reduce((acc, key) => {
      if (params[key]) {
        acc[key] = String(params[key]);
      }
      return acc;
    }, {});

    const searchParams = new URLSearchParams(stringParams);
    const queryString = searchParams.toString();
    const apiPathMessage = `${apiPath}?${queryString}`;
    message = `${apiPathMessage}${nonce}`;
  }

  const hash = crypto.createHash("sha256");
  hash.update(message, "utf8");
  const messageDigest = hash.digest();

  const sign = crypto.createSign("SHA256");
  sign.update(messageDigest);
  sign.end();

  const signature = sign.sign(privateKey, "base64");
  return { signature, nonce };
};

module.exports = { signRequest };

La forma de firmar la solicitud depende del tipo de petición:

• Solicitudes con cuerpo (POST, PATCH, PUT): Se firma el contenido del cuerpo junto con un nonce.
• Solicitudes con parámetros de consulta (GET, DELETE): Se firma el path, los parámetros de consulta (queryParams) y el nonce.

Ejemplo de Solicitud para Crear un Quote (POST)

Al crear un quote, la firma se genera utilizando el cuerpo de la solicitud y un nonce para garantizar que la solicitud sea segura.

Pasos para Firmar la Solicitud POST

1. Genera un nonce: Un valor único basado en un timestamp.
2. Crea el mensaje: Concatenar el body de la solicitud con el nonce.
3. Genera la firma: Usa tu clave privada para generar una firma HMAC del mensaje.

Mensaje para POST: body + nonce

Ejemplo de Solicitud POST para Crear un Quote

POST /quotation
Host: baseUrl
nonce: 1657891234567
signature: <firma_generada>
Content-Type: application/json

{
  "sourceCountry": "US",
  "sourceCurrency": "USD",
  "targetCountry": "VE",
  "targetCurrency": "VES",
  "amount": 1000,
  "payoutType": "BANK_TRANSFER",
  "amountType": "SOURCE"
}

En este ejemplo, el mensaje para firmar sería:

{"sourceCountry":"US","sourceCurrency":"USD","targetCountry":"VE","targetCurrency":"VES","amount":1000,"payoutType":"BANK_TRANSFER","amountType":"SOURCE"}1657891234567

Donde el cuerpo de la solicitud se concatena con el nonce para crear el mensaje a firmar.

Ejemplo de Solicitud para Obtener un Quote por ID (GET)

Para solicitudes GET, como obtener un quote específico por su ID, se firma el path y el nonce.

Pasos para Firmar la Solicitud GET

1. Genera un nonce: Utiliza un timestamp único para cada solicitud.
2. Crea el mensaje: Concatenar el path y el nonce.
3. Genera la firma: Firma el mensaje utilizando tu clave privada.

Mensaje para GET: path + nonce

Ejemplo de Solicitud GET para Obtener un Quote por ID

GET /quotation/12345
Host: baseUrl
nonce: 1657891234567
signature: <firma_generada>

En este ejemplo, el mensaje para firmar sería:

/quotation/123451657891234567

Donde /quotation/12345 es el path de la solicitud y 1657891234567 es el nonce.

Ejemplo de Solicitud GET para con Query Params

GET /balance?currency=USD&date=2024-10-01
Host: baseUrl
nonce: 1657891234567
signature: <firma_generada>

En este ejemplo, el mensaje para firmar sería:

/balance?currency=USD&date=2024-10-011657891234567

Donde /balance es el path, currency=USD&date=2024-10-01 son los queryParams en orden alfabético, y 1657891234567 es el nonce.

Importante:

Los parámetros de consulta (queryParams) deben estar en orden alfabético para asegurar que la firma sea consistente y válida. Esto significa que si tienes múltiples parámetros, deben ser ordenados alfabéticamente antes de generar la firma.