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

import { createSign } from "node:crypto";

const signRequest = ({ apiPath, body, params, privateKey }: {
    apiPath?: string;
    body?: any;
    params?: Record<string, any>;
    privateKey: string;
}): { signature: string; nonce: string } => {
    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 signer = createSign("RSA-SHA256");
      signer.update(message, "utf8");
      signer.end();

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

export { 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 de la solicitud
   • El indicador de inicio de parámetros de consulta ? (siempre, inclusive en la ausencia de párametros de consulta)
   • Los queryParams (parámetros de consulta) si existen
   • El nonce.

3. Genera la firma: Firma el mensaje utilizando tu clave privada.

Mensaje para GET: path + `?` + queryParams + 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/12345?1657891234567

Donde /quotation/12345 es el path de la solicitud,? es el indicador de inicio de query params y 1657891234567 es el nonce.

Ejemplo de Solicitud GET 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, ? es el indicador de inicio de query params, 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.