Guardar datos en tiempo real: del JSON a la base
Cómo almacenar lo que llega de una API en vivo: clave única, upsert, huso horario, detección de huecos y el backfill que cierra la ventana caída.
Publicado el 30 de octubre de 2026 · 6 min de lectura
Recibir el dato es la parte fácil. Lo que da trabajo es guardarlo de una forma que, seis meses después, te permita mirar el historial y confiar en él: sin ronda repetida, sin hueco silencioso y sin esa duda de "¿esta hora es de dónde?". Este artículo es el camino del JSON que llega de la API hasta una tabla que consultás sin miedo.
Vale para cualquier API de datos continuos. Los ejemplos usan las rondas de nuestras APIs de casino en vivo, donde cada registro tiene un id fijo y una hora de cierre — el mismo formato que encontrás en la documentación.
La decisión que resuelve la mitad de los problemas: clave única
Todo dato que llega tiene un identificador del lado de quien lo produjo. Usá ese como clave primaria, no un AUTOINCREMENT tuyo.
CREATE TABLE rondas ( id TEXT PRIMARY KEY, -- el id que viene de la API, fijo y estable juego TEXT NOT NULL, settled_at TEXT NOT NULL, -- ISO 8601 en UTC, como llega outcome TEXT NOT NULL, datos TEXT NOT NULL -- el objeto data original, en JSON ); CREATE INDEX rondas_por_tiempo ON rondas (juego, settled_at);
Con eso, grabar dos veces la misma ronda deja de ser un bug y pasa a ser un no-evento:
import json
import sqlite3
base = sqlite3.connect("rondas.db")
def guardar(ronda):
base.execute(
"INSERT INTO rondas (id, juego, settled_at, outcome, datos) VALUES (?, ?, ?, ?, ?)"
" ON CONFLICT(id) DO NOTHING",
(ronda["id"], ronda["game"], ronda["settledAt"], ronda["outcome"], json.dumps(ronda["data"])),
)
base.commit()El ON CONFLICT DO NOTHING (o INSERT ... ON CONFLICT (id) DO UPDATE en Postgres, si querés sobrescribir) hace que tu grabador sea idempotente: puede correr dos veces, puede reprocesar un archivo, puede reiniciarse en el medio — el resultado es el mismo. Eso es lo que permite dormir tranquilo con reconexiones, repeticiones y el event: ready del stream, que repite la última ronda a propósito.
Guardá el objeto original al lado
Además de las columnas que consultás, guardá el JSON como vino. Cuesta poco y resuelve el problema de dentro de un mes, cuando quieras una información que no se volvió columna — las cartas de cada lado, el multiplicador, el par. Reprocesar a partir del original es trivial; inventar un dato que tiraste, imposible.
UTC en la base, huso solo en la pantalla
La API devuelve fechas en UTC, con la Z al final: "2026-10-30T18:10:58.903Z". Guardá exactamente eso y convertí solo al mostrar.
Por qué: la hora local tiene horario de verano, tiene usuarios en otro huso y tiene una hora ambigua por año. UTC no tiene nada de eso, y ordenar texto ISO 8601 en UTC da el orden cronológico gratis.
from datetime import datetime
from zoneinfo import ZoneInfo
def local(iso, huso="America/Argentina/Buenos_Aires"):
return datetime.fromisoformat(iso.replace("Z", "+00:00")).astimezone(ZoneInfo(huso))
print(local("2026-10-30T18:10:58.903Z").strftime("%d/%m %H:%M:%S")) # 30/10 15:10:58Si tu base es Postgres, usá timestamptz; en SQLite, el texto ISO resuelve bien.
El backfill: cerrando la ventana en que estuviste afuera
Toda recolección en vivo tiene un hueco en algún momento: despliegue, caída de red, reinicio. La forma de cerrarlo es pedir lo que pasó, y para eso existe el parámetro after, que recibe el id de la última ronda que tenés y devuelve solo lo que vino después, en orden cronológico.
def sincronizar(ultimo_id, clave):
"""Pide todo lo que cerró después de ultimo_id, paginando hasta estar al día."""
while True:
cuerpo = pedir("/bacbo-live/results", clave, {"after": ultimo_id, "limit": 250})
for ronda in cuerpo:
guardar(ronda)
ultimo_id = ronda["id"]
if len(cuerpo) < 250:
return ultimo_idEse pedir es el cliente con tratamiento de errores y backoff del artículo sobre errores y límites de una API. Llamá al sincronizar cada vez que el programa arranque, antes de empezar a escuchar en vivo: es una llamada barata cuando no hay nada para traer y es lo que mantiene el historial sin huecos cuando hay.
Quien usa el /stream tiene un atajo: al reconectar con el last-event-id, las rondas de la ausencia vuelven en el propio evento ready, hasta 50. El after queda para ausencias mayores que eso — los detalles están en resultados en tiempo real.
Cómo descubrir un hueco que ni sabías que tenías
Esta es la consulta más útil de todas, y casi nadie la escribe: ¿dónde el intervalo entre registros consecutivos es demasiado grande? Si la mesa corre una ronda cada ~35 segundos, un intervalo de 3 minutos es un hueco, no una pausa.
WITH seq AS (
SELECT settled_at,
LAG(settled_at) OVER (PARTITION BY juego ORDER BY settled_at) AS anterior
FROM rondas WHERE juego = 'bacbo-live'
)
SELECT anterior, settled_at,
(julianday(settled_at) - julianday(anterior)) * 86400 AS segundos
FROM seq
WHERE segundos > 90
ORDER BY segundos DESC;Correla una vez por semana. Fue exactamente ese tipo de consulta la que mostró, en una comparación ronda por ronda, que una fuente conocida dejaba cerca del 20% de las rondas afuera — los huecos aparecieron en su lista, no en la nuestra.
Dónde guardarlo, según el tamaño
| Volumen | Dónde | Por qué |
|---|---|---|
| Hasta algunos cientos de miles de filas | SQLite | Un solo archivo, sin servidor, y ya tiene ventana (LAG) e índices |
| Millones de filas, varios lectores | Postgres | Concurrencia, timestamptz, JSONB y upsert de verdad |
| Solo análisis, una vez | CSV o Parquet | Abre en Excel, Sheets o pandas sin instalar nada |
Una mesa de casino en vivo corre cerca de 2.500 rondas por día, o cerca de 1 millón por año. Es poco para cualquier base y mucho para una planilla — por eso el camino común es base para guardar y CSV para analizar.
Un error común: dos grabadores en la misma tabla
Si tu bot de Telegram y tu sitio graban en la misma tabla, en algún momento los dos van a intentar grabar la misma ronda en el mismo instante. Con clave única eso es inofensivo — uno graba, el otro recibe conflicto y sigue. Sin clave única, te despertás con filas duplicadas y estadísticas equivocadas.
Si podés, dejá un proceso grabando y los otros leyendo. Es más fácil de entender y de depurar que cualquier traba.
Checklist antes de confiar en tu historial
- El
idde la fuente es la clave primaria, y la grabación es idempotente. - Las fechas están en UTC en la base, y el huso aparece solo en la pantalla.
- El programa llama al backfill al arrancar.
- Existe una consulta de huecos, y alguien mira su resultado.
- El JSON original está guardado, no solo las columnas de hoy.
- El volumen cabe en la base elegida, con índice en el campo de tiempo.
Preguntas frecuentes
- ¿Cuál debe ser la clave primaria de una tabla de datos de API?
El identificador que viene de la propia API, no un autoincremento tuyo. Es fijo y estable, así que una grabación repetida se vuelve conflicto silencioso en vez de fila duplicada, y eso hace que tu grabador sea idempotente.
- ¿Debo guardar las fechas en UTC o en hora local?
En UTC, exactamente como las devuelve la API, y convertir solo al mostrar. La hora local trae horario de verano, usuarios en otro huso y una hora ambigua por año; ordenar texto ISO 8601 en UTC ya da el orden cronológico.
- ¿Cómo recupero los datos del período en que mi programa estuvo caído?
Con el parámetro after del endpoint de historial: pasás el id de la última fila que tenés y recibís solo lo que vino después, paginando hasta estar al día. Llamalo cada vez que el programa arranque. Quien usa el /stream recibe hasta 50 rondas de la ausencia en el propio evento ready al reconectar con last-event-id.
- ¿Cómo sé si falta algún dato en mi historial?
Comparando el intervalo entre registros consecutivos con el ritmo normal de la fuente, con una consulta de ventana (LAG). Los intervalos muy por encima de lo esperado son huecos, y esa es la verificación que revela una recolección incompleta antes de que arruine tus estadísticas.
Lee también
- Qué es una API y cómo conectarse a una por primera vez
API explicada sin complicaciones: qué es, cómo funcionan REST, JSON y las claves, y cómo hacer la primera llamada en el navegador, la terminal, Python y JavaScript.
- Cómo leemos una mesa en vivo: del video al JSON
El camino de un resultado de la mesa a la API: segmentos de video, red neuronal, la verificación por las reglas del juego y por qué descartamos antes que adivinar.
- ¿Raspar el sitio o usar una API? El costo real
El web scraping parece gratis, pero se rompe con el layout, el login y los bloqueos. Cuándo tiene sentido un raspador y cuándo sale más barata una API.