91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
# 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):
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"statusResponse": {
|
|
"status": "ok",
|
|
"statusCode": "200",
|
|
"message": "Operación exitosa",
|
|
"traceId": "c983d7aa-c81b-4f99-923f-e14b512c0199"
|
|
},
|
|
"data": {
|
|
"cuentas": [
|
|
{ "id": "1", "saldo": 5000 }
|
|
]
|
|
}
|
|
}
|
|
```
|