Blog · General

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:58

Si 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_id

Ese 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

VolumenDóndePor qué
Hasta algunos cientos de miles de filasSQLiteUn solo archivo, sin servidor, y ya tiene ventana (LAG) e índices
Millones de filas, varios lectoresPostgresConcurrencia, timestamptz, JSONB y upsert de verdad
Solo análisis, una vezCSV o ParquetAbre 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 id de 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