Cache de respuestas

Las lecturas (GET) sobre /products, /customers, /leads y /automations pueden servirse desde una capa de Redis dedicada por cuenta. El cache es opt-in y se prende desde el dashboard de developers → Ajustes → Cache de respuestas.

Por qué activarlo

• Latencia plana: una respuesta cacheada se devuelve en ~5 ms sin tocar Mongo.
• Menor factura: un GET cacheado no genera el cargo de Mongo — solo el de Redis (mucho más barato) y el de Cloud Run por el tiempo de servir bytes. Los detalles están en cada UsageEvent que generamos (campos cost_cents_mongo, cost_cents_redis, cache_hit).
• Sin trabajo del lado del cliente: tu integración no cambia. Se mantiene la misma URL, los mismos params (incluidos ?starting_after= y ?include_total=), la misma forma de respuesta.

Cómo funciona

1. Activas el toggle y eliges un TTL entre 10 s y 3600 s (default 60 s).
2. La primera vez que un cliente con tu API key hace un GET con un set de query params dado, ejecutamos la consulta normal y guardamos el cuerpo en Redis. Respondemos con el header X-Cache: MISS.
3. Llamadas siguientes con los mismos query params dentro del TTL son atendidas desde Redis. Respondemos con X-Cache: HIT.
4. Cualquier POST, PATCH o DELETE sobre el mismo recurso (ej. crear un producto) invalida automáticamente todas las entradas cacheadas de ese recurso para tu empresa, en O(1). El próximo GET será un MISS.

El cache se aísla por:

• Empresa: ningún tenant ve datos cacheados de otro, ni siquiera si comparten cuenta de developers.
• Query params: ?limit=10 y ?limit=20 ocupan slots separados; ?starting_after= también.
• Recurso: invalidar productos no afecta el cache de clientes.

Headers que respondemos

Header	Valores	Descripción
X-Cache	HIT / MISS	Solo presente cuando el cache está activo. HIT significa que la respuesta vino de Redis; MISS, que se reconsultó la fuente y se guardó.

Si no activaste el cache, ningún X-Cache aparece en la respuesta.

Impacto en costo

Cada operación de cache se contabiliza:

Escenario	Mongo	Redis (escrituras + lecturas)	Total relativo
Cache off (default)	1 read	0	base
Cache on, MISS	1 read	2 ops (1 read miss + 1 write)	base + delta menor
Cache on, HIT	0 reads	1 op (1 read)	mucho menos que base
Cualquier POST / PATCH / DELETE	1 write	1 op (invalidación)	base + delta menor

Para workloads donde lees el mismo listado varias veces antes de mutarlo (catálogos públicos, dashboards internos, motores de búsqueda que recargan al cambiar de pestaña), el cache siempre reduce el costo total. Para workloads de pura escritura sin re-lectura, el costo es marginalmente mayor — en ese caso déjalo apagado.

Cuándo apagarlo

• Cuando el cliente final necesita ver lecturas estrictamente consistentes con el último escribir (transferencias bancarias, cierres de turno) — aunque incluso ahí el TTL de 10 s suele ser aceptable y las escrituras invalidan en O(1).
• Cuando casi no haces GET repetidos sobre el mismo set de params.

Al apagar el toggle, bumpamos inmediatamente las versiones internas de cada recurso así que los hits dejan de ocurrir en cuanto guardas. No esperes a que expire el TTL.

Ejemplo

# Primera vez
curl -i 'https://developers.fi-nova.com/api/v1/products?limit=10' \
  -H 'Authorization: Bearer finova_sk_…'

HTTP/1.1 200 OK
X-Cache: MISS
Content-Type: application/json
...

# Segunda vez (dentro del TTL)
curl -i 'https://developers.fi-nova.com/api/v1/products?limit=10' \
  -H 'Authorization: Bearer finova_sk_…'

HTTP/1.1 200 OK
X-Cache: HIT
Content-Type: application/json
...

El segundo request es ~5 ms vs ~50 ms del primero, y el UsageEvent registra cache_hit: true, cost_cents_mongo: 0.