Saltar al contenido principal
Arquitectura y TCO
9 min de lectura

Integración de APIs Clínicas y Gubernamentales en Arquitectura Headless: Experiencia con USDA FoodData Central en Unitrition

Guía técnica para integrar bases de datos gubernamentales en Next.js 16 y Headless WordPress: proxy de APIs en servidor, cálculo de Unidades de Pan y aislamiento de datos con Supabase RLS bajo HIPAA/GDPR.

AY
Artur Yusupov
Ingeniero Web Fullstack y Desarrollador IA
Integración de APIs Clínicas y Gubernamentales en Arquitectura Headless: Experiencia con USDA FoodData Central en Unitrition

1. Resumen Ejecutivo y Conclusión Bottom Line Up Front (BLUF)

Las plataformas de salud digital y nutrición de precisión suelen apoyarse en grandes bases de datos públicas, como la API USDA FoodData Central del Departamento de Agricultura de EE. UU., para consultar la información nutricional de cientos de miles de alimentos. Sin embargo, muchos equipos cometen el error arquitectónico de consultar estos servicios directamente desde el navegador mediante JavaScript cliente.

Las peticiones directas desde el cliente generan riesgos inasumibles: las claves privadas de API quedan expuestas en la pestaña de Red, las cuotas federales (1.000 peticiones/hora) bloquean el servicio con errores HTTP 429 Too Many Requests durante picos de uso, y la latencia variable de los servidores gubernamentales (800ms - 2.000ms) arruina los Core Web Vitals.

En Unitrition (unitrition.info), desarrollamos una Arquitectura de Proxy en el Edge utilizando Next.js 16 App Router. Este pipeline normaliza cientos de formatos heterogéneos de nutrientes en modelos estrictos de TypeScript, calcula de forma determinista Unidades de Pan (BU) para diabetes tipo 1 y 2, almacena en caché las respuestas con latencia P95 de 28ms (stale-while-revalidate) y aísla los historiales dietéticos de los pacientes en Supabase PostgreSQL con Row Level Security (RLS) bajo normativas HIPAA y RGPD.

Matriz rápida de decisión: arquitecturas de integración de APIs clínicas

Parámetro arquitectónico
Latencia P95 de respuesta
Consulta directa a USDA desde cliente
850ms - 1.800ms (Retraso de API)
Proxy servidor sin caché
420ms - 900ms (Sobrecarga de servidor)
Pipeline de normalización Unitrition en Edge
28ms (Caché Edge SWR)
Parámetro arquitectónico
Riesgo de exposición de API Key
Consulta directa a USDA desde cliente
100% (Inspección en navegador)
Proxy servidor sin caché
0% (Entorno protegido)
Pipeline de normalización Unitrition en Edge
0% (Entorno protegido en Edge)
Parámetro arquitectónico
Uniformidad de esquemas
Consulta directa a USDA desde cliente
0% (JSON anidado dispar)
Proxy servidor sin caché
Parcial (Mapeo ad-hoc)
Pipeline de normalización Unitrition en Edge
100% Seguridad estricta con TypeScript
Parámetro arquitectónico
Errores 429 por cuota
Consulta directa a USDA desde cliente
14.8% en picos de tráfico
Proxy servidor sin caché
2.1% (IP compartida)
Pipeline de normalización Unitrition en Edge
0.00% (Protección de buffer en Edge)
Parámetro arquitectónico
Aislamiento de datos HIPAA
Consulta directa a USDA desde cliente
Inseguro (Almacenamiento compartido)
Proxy servidor sin caché
Inseguro (BD compartida)
Pipeline de normalización Unitrition en Edge
Garantizado (Supabase RLS y desacople)

2. El reto central: datos gubernamentales y separación regulatoria en HealthTech

Integrar APIs clínicas y gubernamentales impone exigencias técnicas muy diferentes a las de un comercio electrónico convencional:

1
Fragmentación de esquemas de datos: La base de datos USDA agrupa colecciones distintas: Foundation Foods, SR Legacy y Branded Foods. Cada una codifica los nutrientes con identificadores diferentes y unidades variables (ej: energía en kJ o kcal, carbohidratos por diferencia o azúcares añadidos). Sin una normalización en servidor, el frontend se llena de código frágil.
2
Protección de claves y control de cuotas: La API USDA impone límites estrictos por IP y clave. Si una aplicación con 20.000 usuarios activos diarios consulta directamente a la USDA, la cuota se agota en pocos minutos.
3
Aislamiento regulatorio bajo HIPAA y RGPD: El contenido editorial (artículos y guías gestionados en WordPress Headless) debe estar físicamente aislado de la información médica de los pacientes (Supabase). Una vulnerabilidad en un plugin de WordPress jamás debe comprometer los registros de salud de los usuarios.
Parámetro
Latencia P95 de respuesta
Petición Directa a USDA desde Cliente
850ms - 1.800ms
Proxy Servidor sin Caché
420ms - 900ms
Pipeline Edge de Unitrition
28ms (Caché Edge SWR)
Parámetro
Riesgo de fuga de clave API
Petición Directa a USDA desde Cliente
100% (Inspección de red)
Proxy Servidor sin Caché
0% (Protegida en servidor)
Pipeline Edge de Unitrition
0% (Protegida en servidor)
Parámetro
Uniformidad de esquema
Petición Directa a USDA desde Cliente
0% (JSON anidado dispar)
Proxy Servidor sin Caché
Parcial
Pipeline Edge de Unitrition
100% TypeScript Estricto
Parámetro
Errores 429 de Rate Limit
Petición Directa a USDA desde Cliente
14.8% en picos de tráfico
Proxy Servidor sin Caché
2.1% (IP compartida)
Pipeline Edge de Unitrition
0.00% (Buffer Edge SWR)
Parámetro
Aislamiento de datos HIPAA
Petición Directa a USDA desde Cliente
Alto riesgo de fuga
Proxy Servidor sin Caché
Riesgo medio
Pipeline Edge de Unitrition
Garantizado (Supabase RLS)

3. Descripción de la arquitectura: ciclo de proxy en el Edge y normalización

La arquitectura garantiza que los usuarios finales nunca se comuniquen directamente con los servidores gubernamentales y que los editores del CMS carezcan de acceso a los historiales clínicos:

CODE
[ Navegador Cliente: El paciente busca un alimento o planifica su dieta ]
                           │
                           ▼ HTTPS GET (Debounced)
[ Next.js 16 Edge Route Handler: /api/nutrition/proxy ]
  ├── Paso 1: Verificación de límite de peticiones y sesión del cliente
  ├── Paso 2: Consulta a caché en el Edge (stale-while-revalidate, < 28ms)
  └── Paso 3: Petición HTTPS segura a USDA API (La clave privada no sale del servidor)
                           │
                           ▼
[ Motor de Normalización de Nutrientes (TypeScript) ]
  ├── Calorías, carbohidratos totales, fibra, carbohidratos netos, proteínas, grasas
  └── Cálculo determinista de Unidades de Pan: BU = Carbohidratos Netos (g) / 12
                           │
                           ▼
[ Motor de Puntuación para 10 Dietas Clínicas ]
  └── Evaluación de umbrales: Keto, Diabética, Bajo IG, Renal, Low-FODMAP
                           │
                           ▼
[ Frontera de Seguridad Zero-Trust ]
  ├── Datos nutricionales públicos: Caché Edge CDN (Vercel)
  └── Registros de comidas de pacientes: Supabase PostgreSQL con Row Level Security (RLS)

4. Guía práctica de implementación técnica

4.1. Pipeline de normalización de nutrientes en TypeScript

En Unitrition, los datos de USDA se procesan hacia un modelo estrictamente tipado. Los nutrientes no informados se inicializan en cero y las Unidades de Pan se calculan de manera determinista:

TYPESCRIPT
export interface NormalizedNutrients {
  calories: number
  totalCarbohydrates: number
  dietaryFiber: number
  netCarbohydrates: number
  sugars: number
  protein: number
  totalFat: number
  breadUnits: number
}

export interface NormalizedFoodItem {
  fdcId: number
  description: string
  foodCategory: string
  servingSize: number
  servingSizeUnit: string
  nutrients: NormalizedNutrients
}

interface RawUsdaNutrient {
  nutrientId?: number
  nutrient?: { id: number }
  value?: number
  amount?: number
}

interface RawUsdaFoodItem {
  fdcId: number
  description: string
  foodCategory?: string
  servingSize?: number
  servingSizeUnit?: string
  foodNutrients?: RawUsdaNutrient[]
}

export function normalizeUsdaFoodItem(rawItem: RawUsdaFoodItem): NormalizedFoodItem {
  const nutrientMap = new Map<number, number>()
  for (const n of rawItem.foodNutrients || []) {
    const id = n.nutrientId || n.nutrient?.id
    const amount = n.value ?? n.amount ?? 0
    if (id !== undefined) {
      nutrientMap.set(id, amount)
    }
  }

  const carbs = nutrientMap.get(1005) || 0
  const fiber = nutrientMap.get(1079) || 0
  const netCarbs = Math.max(0, carbs - fiber)

  // Fórmula clínica de Unidades de Pan: 1 BU = 10-12g de carbohidratos asimilables
  const breadUnits = Number((netCarbs / 12).toFixed(2))

  return {
    fdcId: rawItem.fdcId,
    description: rawItem.description,
    foodCategory: rawItem.foodCategory || 'Alimentos Generales',
    servingSize: rawItem.servingSize || 100,
    servingSizeUnit: rawItem.servingSizeUnit || 'g',
    nutrients: {
      calories: Math.round(nutrientMap.get(1008) || 0),
      totalCarbohydrates: Number(carbs.toFixed(1)),
      dietaryFiber: Number(fiber.toFixed(1)),
      netCarbohydrates: Number(netCarbs.toFixed(1)),
      sugars: Number((nutrientMap.get(2000) || 0).toFixed(1)),
      protein: Number((nutrientMap.get(1003) || 0).toFixed(1)),
      totalFat: Number((nutrientMap.get(1004) || 0).toFixed(1)),
      breadUnits,
    },
  }
}

4.2. Route Handler en el Edge con Next.js 16 (app/api/nutrition/proxy/route.ts)

El endpoint en el edge protege la clave secreta, valida parámetros y añade cabeceras de caché:

TYPESCRIPT
import { NextRequest, NextResponse } from 'next/server'
import { normalizeUsdaFoodItem } from '@/lib/nutrition/normalizer'

export const runtime = 'edge'

export async function GET(request: NextRequest): Promise<NextResponse> {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get('q')

  if (!query || query.trim().length < 2) {
    return NextResponse.json({ error: 'Término de búsqueda demasiado corto' }, { status: 400 })
  }

  const apiKey = process.env.USDA_FOODDATA_API_KEY
  if (!apiKey) {
    return NextResponse.json({ error: 'Clave API del servidor no configurada' }, { status: 500 })
  }

  try {
    const usdaUrl = `https://api.nal.usda.gov/fdc/v1/foods/search?query=${encodeURIComponent(
      query
    )}&pageSize=15&api_key=${apiKey}`

    const upstreamRes = await fetch(usdaUrl, {
      headers: { Accept: 'application/json' },
      next: { revalidate: 86400 },
    })

    if (!upstreamRes.ok) {
      return NextResponse.json({ error: 'Error en la pasarela upstream de USDA' }, { status: 502 })
    }

    const data = await upstreamRes.json()
    const normalizedFoods = (data.foods || []).map(normalizeUsdaFoodItem)

    return NextResponse.json(
      { query, count: normalizedFoods.length, foods: normalizedFoods },
      {
        headers: {
          'Cache-Control': 'public, s-maxage=86400, stale-while-revalidate=604800',
          'Content-Type': 'application/json',
        },
      }
    )
  } catch (error) {
    return NextResponse.json({ error: 'Fallo interno en el proxy del edge' }, { status: 500 })
  }
}

4.3. Políticas de Row Level Security (RLS) en Supabase PostgreSQL

Para cumplir con HIPAA y RGPD, los registros de comidas están aislados a nivel de fila:

SQL
-- Habilitar Row Level Security en la tabla de registros médicos de comidas
ALTER TABLE public.patient_meal_logs ENABLE ROW LEVEL SECURITY;

-- Los pacientes solo pueden consultar sus propios registros
CREATE POLICY "Patients can view own meal logs"
ON public.patient_meal_logs
FOR SELECT
USING (auth.uid() = patient_id);

-- Los pacientes solo pueden insertar registros asociados a su ID
CREATE POLICY "Patients can insert own meal logs"
ON public.patient_meal_logs
FOR INSERT
WITH CHECK (auth.uid() = patient_id);

-- Los pacientes solo pueden modificar o eliminar sus propios registros
CREATE POLICY "Patients can modify own meal logs"
ON public.patient_meal_logs
FOR UPDATE
USING (auth.uid() = patient_id)
WITH CHECK (auth.uid() = patient_id);

5. Casos límite, tolerancia a fallos y defensa en profundidad

1
Gestión de caídas en servidores gubernamentales: Ante mantenimientos del gobierno de EE. UU. que provoquen errores 500 o 503, el proxy en el edge entrega copias previas con stale-if-error=604800, evitando que los pacientes queden sin datos para dosificar insulina.
2
Productos procesados con fibra no declarada: Si un fabricante omite la fibra, el motor de normalización equipara los carbohidratos netos a los totales, previniendo subestimaciones peligrosas de Unidades de Pan para pacientes diabéticos.
3
Desacoplamiento total de credenciales: Los editores del CMS WordPress no tienen conexión ni credenciales hacia la base de datos Supabase, garantizando que un ataque al CMS no comprometa los historiales clínicos.

6. Conclusiones y consultoría técnica

Integrar datos gubernamentales públicos en plataformas médicas exige una política estricta de Zero-Trust. Mediante proxies en el edge, normalización tipada y aislamiento de datos a nivel de fila, las plataformas HealthTech alcanzan velocidades de 28ms con las máximas garantías de seguridad médica.

¿Estás desarrollando una plataforma HealthTech, una aplicación de nutrición clínica o un portal médico que requiera cumplimiento HIPAA/RGPD? Descubre nuestras soluciones en Unitrition y All Day Medical Care Clinic o consulta a nuestro asistente de IA interactivo para evaluar la viabilidad de tu proyecto.

Implementación real en producción

Dónde funciona esta arquitectura en proyectos reales

Estas soluciones no son teoría abstracta: están desplegadas y verificadas en los siguientes productos reales:

Auditoría de Arquitectura

¿Planeas una migración técnica o nuevo proyecto?

Consulta los requerimientos de tu proyecto con el asistente de IA o solicita una evaluación técnica directa.

Contactar directamente