Blog · Geral

Guardar dados em tempo real: do JSON ao banco, sem perder

Como armazenar os dados que chegam de uma API ao vivo: chave única, upsert, fuso horário, detecção de buracos e o backfill que fecha a janela fora do ar.

Publicado em 30 de outubro de 2026 · 6 min de leitura

Receber o dado é a parte fácil. O que dá trabalho é guardá-lo de um jeito que, seis meses depois, você consiga olhar o histórico e confiar nele: sem rodada repetida, sem buraco silencioso e sem aquela dúvida de "esse horário é de onde?". Este artigo é o caminho do JSON que chega da API até uma tabela que você consulta sem medo.

Vale para qualquer API de dados contínuos. Os exemplos usam as rodadas das nossas APIs de cassino ao vivo, onde cada registro tem um id fixo e um horário de fechamento — o mesmo formato que você encontra na documentação.

A decisão que resolve metade dos problemas: chave única

Todo dado que chega tem um identificador do lado de quem produziu. Use ele como chave primária, não um AUTOINCREMENT seu.

CREATE TABLE rodadas (
  id          TEXT PRIMARY KEY,   -- o id que vem da API, fixo e estável
  jogo        TEXT NOT NULL,
  settled_at  TEXT NOT NULL,      -- ISO 8601 em UTC, como chega
  outcome     TEXT NOT NULL,
  dados       TEXT NOT NULL       -- o objeto data original, em JSON
);
CREATE INDEX rodadas_por_tempo ON rodadas (jogo, settled_at);

Com isso, gravar duas vezes a mesma rodada deixa de ser um bug e passa a ser um não-evento:

import json
import sqlite3

banco = sqlite3.connect("rodadas.db")

def gravar(rodada):
    banco.execute(
        "INSERT INTO rodadas (id, jogo, settled_at, outcome, dados) VALUES (?, ?, ?, ?, ?)"
        " ON CONFLICT(id) DO NOTHING",
        (rodada["id"], rodada["game"], rodada["settledAt"], rodada["outcome"], json.dumps(rodada["data"])),
    )
    banco.commit()

O ON CONFLICT DO NOTHING (ou INSERT ... ON CONFLICT (id) DO UPDATE no Postgres, se você quiser sobrescrever) torna o seu gravador idempotente: pode rodar duas vezes, pode reprocessar um arquivo, pode reiniciar no meio — o resultado é o mesmo. Isso é o que permite dormir tranquilo com reconexões, repetições e o event: ready do stream, que repete a última rodada de propósito.

Guarde o objeto original junto

Além das colunas que você consulta, guarde o JSON como veio. Custa pouco e resolve o problema de dentro de um mês, quando você quiser uma informação que não virou coluna — as cartas de cada lado, o multiplicador, o par. Reprocessar a partir do original é trivial; inventar um dado que você jogou fora, impossível.

UTC no banco, fuso só na tela

A API devolve datas em UTC, com o Z no fim: "2026-10-30T18:10:58.903Z". Guarde exatamente assim e converta só na hora de mostrar.

Por quê: horário local tem horário de verão, tem usuário em outro fuso e tem ambiguidade de uma hora por ano. UTC não tem nada disso, e ordenar texto ISO 8601 em UTC dá a ordem cronológica de graça.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

def local(iso, fuso="America/Sao_Paulo"):
    return datetime.fromisoformat(iso.replace("Z", "+00:00")).astimezone(ZoneInfo(fuso))

print(local("2026-10-30T18:10:58.903Z").strftime("%d/%m %H:%M:%S"))   # 30/10 15:10:58

Se o seu banco é Postgres, use timestamptz; no SQLite, texto ISO resolve bem.

O backfill: fechando a janela em que você estava fora

Toda coleta ao vivo tem um buraco em algum momento: deploy, queda de rede, reinício. O jeito de fechar é pedir o que passou, e para isso existe o parâmetro after, que recebe o id da última rodada que você tem e devolve só o que veio depois, em ordem cronológica.

def sincronizar(ultimo_id, chave):
    """Pede tudo o que fechou depois de ultimo_id, paginando até ficar em dia."""
    while True:
        corpo = pedir("/bacbo-live/results", chave, {"after": ultimo_id, "limit": 250})
        for rodada in corpo:
            gravar(rodada)
            ultimo_id = rodada["id"]
        if len(corpo) < 250:
            return ultimo_id

O pedir aí é o cliente com tratamento de erro e backoff do artigo sobre erros e limites de uma API. Chame o sincronizar sempre que o programa subir, antes de começar a ouvir ao vivo: é uma chamada barata quando não há nada para trazer e é o que mantém o histórico sem buraco quando há.

Quem usa o /stream tem um atalho: ao reconectar com o last-event-id, as rodadas da ausência voltam no próprio evento ready, até 50. O after fica para ausências maiores que isso — os detalhes estão em resultados em tempo real.

Como descobrir um buraco que você nem sabia que tinha

Essa é a consulta mais útil de todas, e quase ninguém escreve: onde o intervalo entre registros consecutivos é grande demais? Se a mesa roda uma rodada a cada ~35 segundos, um intervalo de 3 minutos é um buraco, não uma pausa.

WITH seq AS (
  SELECT settled_at,
         LAG(settled_at) OVER (PARTITION BY jogo ORDER BY settled_at) AS anterior
  FROM rodadas WHERE jogo = 'bacbo-live'
)
SELECT anterior, settled_at,
       (julianday(settled_at) - julianday(anterior)) * 86400 AS segundos
FROM seq
WHERE segundos > 90
ORDER BY segundos DESC;

Rode isso uma vez por semana. Foi exatamente esse tipo de consulta que mostrou, numa comparação rodada a rodada, que uma fonte conhecida deixava cerca de 20% das rodadas de fora — os buracos apareceram na lista dela, não na nossa.

Onde guardar, conforme o tamanho

VolumeOndePor quê
Até algumas centenas de milhares de linhasSQLiteUm arquivo só, sem servidor, e já tem janela (LAG) e índice
Milhões de linhas, vários leitoresPostgresConcorrência, timestamptz, JSONB e upsert de verdade
Só análise, uma vezCSV ou ParquetAbre no Excel, no Sheets ou no pandas sem instalar nada

Uma mesa de cassino ao vivo roda cerca de 2.500 rodadas por dia, ou perto de 1 milhão por ano. É pouco para qualquer banco e muito para uma planilha — por isso o caminho comum é banco para guardar e CSV para analisar.

Um erro comum: dois gravadores na mesma tabela

Se o seu bot do Telegram e o seu site gravam na mesma tabela, em algum momento os dois vão tentar gravar a mesma rodada no mesmo instante. Com chave única, isso é inofensivo — um grava, o outro recebe conflito e segue. Sem chave única, você acorda com linhas duplicadas e estatísticas erradas.

Se puder, deixe um processo gravando e os outros lendo. É mais simples de entender e de depurar do que qualquer trava.

Checklist antes de confiar no seu histórico

  • O id da fonte é a chave primária, e a gravação é idempotente.
  • As datas estão em UTC no banco, e o fuso aparece só na tela.
  • O programa chama o backfill ao subir.
  • Existe uma consulta de buracos, e alguém olha o resultado dela.
  • O JSON original está guardado, não só as colunas de hoje.
  • O volume cabe no banco escolhido, com índice no campo de tempo.

Perguntas frequentes

Qual deve ser a chave primária de uma tabela de dados de API?

O identificador que vem da própria API, não um autoincremento seu. Ele é fixo e estável, então uma gravação repetida vira conflito silencioso em vez de linha duplicada, e isso torna o seu gravador idempotente.

Devo guardar as datas em UTC ou no horário local?

Em UTC, exatamente como a API devolve, e converter só na hora de mostrar. Horário local traz horário de verão, usuários em outro fuso e uma hora ambígua por ano; ordenar texto ISO 8601 em UTC já dá a ordem cronológica.

Como recuperar os dados do período em que o meu programa ficou fora?

Com o parâmetro after do endpoint de histórico: você passa o id da última linha que tem e recebe só o que veio depois, paginando até ficar em dia. Chame isso sempre que o programa subir. Quem usa o /stream recebe até 50 rodadas da ausência no próprio evento ready ao reconectar com last-event-id.

Como sei se faltou algum dado no meu histórico?

Comparando o intervalo entre registros consecutivos com o ritmo normal da fonte, com uma consulta de janela (LAG). Intervalos muito acima do esperado são buracos, e essa é a verificação que revela uma coleta incompleta antes de ela estragar as suas estatísticas.

Leia também