03 — Contrato de Headers y Trazabilidad (traceId)

Contrato de comunicación entre Cliente, Next.js Server Components y APIs de Downstream

Uso: Esta guía detalla cómo estructurar y propagar los headers de autenticación e identificación del dispositivo, asegurando la trazabilidad del traceId de extremo a extremo.

1. El Ciclo de Vida del `traceId` (Request Correlation)

El traceId es la clave de correlación única generada por el cliente que permite rastrear una petición desde el navegador del usuario, pasando por Next.js App Router, Kong Gateway, hasta llegar a las APIs de Spring Boot y bases de datos.

En nuestro Internet Banking Seguro:

El traceId se toma del valor device.deviceSessionReference enviado por el cliente o del ID de sesión generado por Next.js Middleware.
Se propaga obligatoriamente en todas las cabeceras de las llamadas de servicios HTTP a APIs downstream.

2. Matriz de Headers Requeridos

Cuando Next.js Server Components o Route Handlers realizan peticiones al backend (Spring Boot), deben incluir el siguiente contrato de headers bancarios:

Header	Tipo	Propósito	Fuente en Frontend
`Authorization`	Bearer Token	Autenticación del usuario final	Extraído de la cookie HTTP-only `access_token`
`traceId`	UUID / String	Correlación única de petición	`deviceSessionReference` o UUID de middleware
`appId`	String	Identificación del cliente (ej. portal web)	Variable de entorno (.env) del servidor
`agencyCode`	String	Identificación de la agencia física	Extraído del perfil del usuario (Zustand/Cookie)
`customerReferenceFintechId`	String	Identificación del cliente fintech	Extraído del JWT decodificado en Next.js server

3. Ejemplo Práctico de Propagación de Headers

Al consumir el backend desde una llamada de servidor en Next.js (ej. en una API Route o Server Action):

import { cookies } from 'next/headers';
import { NextRequest } from 'next/server';

export async function fetchCuentasUsuario(deviceSessionId: string) {
  const cookieStore = cookies();
  const token = cookieStore.get('access_token')?.value;

  if (!token) {
    throw new Error('No hay sesión activa para propagar credenciales');
  }

  // Estructuramos el contrato de headers obligatorios
  const headers = new Headers({
    'Authorization': `Bearer ${token}`,
    'traceId': deviceSessionId,
    'appId': process.env.API_APP_ID || 'PORTAL_WEB_SAFE',
    'customerReferenceFintechId': 'FT-1002394', // Extraído previamente del JWT
  });

  const response = await fetch(`${process.env.API_URL_SERVER}/cuentas`, {
    method: 'GET',
    headers: headers,
    next: { revalidate: 60 } // Cache inteligente
  });

  if (!response.ok) {
    throw new Error(`Fallo en backend: ${response.statusText}`);
  }

  return response.json();
}

4. Respuestas del Servidor al Cliente

Las API Routes locales de Next.js (/app/api/...) deben encapsular la respuesta al cliente siguiendo una estructura coherente y propagando el traceId de vuelta para facilitar la depuración:

{
  "statusResponse": {
    "status": "ok",
    "statusCode": "200",
    "message": "Operación exitosa",
    "traceId": "c983d7aa-c81b-4f99-923f-e14b512c0199"
  },
  "data": {
    "cuentas": [
      { "id": "1", "saldo": 5000 }
    ]
  }
}

3.3 KiB Raw Blame History