DEV Community: Vou Embarcar

Public API for Brazilian Lottery Data: OpenAPI Spec and Use Cases

Vou Embarcar — Mon, 21 Sep 2026 19:45:51 +0000

Brazilian lottery data — federal draws, state lotteries, and the culturally embedded jogo do bicho results — has historically been fragmented across dozens of small, unreliable sources. If you were a developer building a Brazilian-market app that needed lottery results as a data feed, your options were:

Scrape a portal (fragile, breaks constantly)
Pay a proprietary vendor (BRL 500-2000/month, minimum-commit contracts)
Build your own scraper stack

None of these are great. Recently I open-sourced the OpenAPI specification and made available a public, read-only, rate-limited HTTP API for Brazilian lottery data at deunobicho.online/api-publica. This post documents the spec, the design decisions, and concrete integration examples.

What the API covers

Six data domains:

Endpoint	What it returns	Update frequency
`/api/loterias/federal`	Federal lottery results	2×/week (Wed & Sat)
`/api/loterias/mega-sena`	Mega-Sena results	2-3×/week
`/api/loterias/lotofacil`	Lotofácil results	6×/week
`/api/loterias/quina`	Quina results	6×/week
`/api/loterias/lotep`	LOTEP (Paraíba state)	Daily
`/api/bicho/{banca}/{turno}`	Jogo do bicho (informal)	5-7×/day

Plus supporting endpoints:

/api/livro-dos-sonhos — 231 dream symbols mapped to groups
/api/prova/{id} — SHA256 evidence for any published result
/api/grupos — the 25 canonical jogo do bicho animal groups

Total surface: about 25 routes, all read-only, all cached at the CDN.

Design decisions

1. Read-only, no auth for the free tier

The vast majority of use cases (personal projects, cultural datasets, aggregation apps) do not need write access or personalization. Removing auth removes friction. Rate limiting is by IP (300 req/min) — enough for any legitimate use, insufficient for scraping-as-service abuse.

2. JSON only, no XML, no SOAP

We are in 2026. Every consumer speaks JSON. Every language has a fetch / curl / requests primitive. Multiplying formats multiplies bugs.

3. `force-static` for archive endpoints

Historical results never change. The archive endpoints are literally pre-built JSON files served from Vercel's edge:

GET /api/loterias/federal/2026-09-18
Cache-Control: public, max-age=31536000, immutable

TTFB from anywhere in the world: 32-80ms. Zero server functions on the hot path.

4. `Last-Modified` and `ETag` on hot endpoints

The "today's results" endpoint returns proper HTTP caching headers:

GET /api/loterias/federal/hoje
Last-Modified: Wed, 18 Sep 2026 19:15:00 GMT
ETag: "8f4a2b1c"
Cache-Control: public, max-age=60, s-maxage=60

If a consumer polls, they can send If-None-Match: "8f4a2b1c" and get a 304 Not Modified — zero bandwidth cost.

5. Consistent envelope

Every response uses:

{
  "meta": {
    "version": "1.0",
    "generated_at": "2026-09-18T19:15:00Z",
    "cache_ttl_seconds": 60,
    "sha256": "a1b2c3..."
  },
  "data": { /* actual payload */ },
  "links": {
    "self": "https://deunobicho.online/api/...",
    "evidence": "https://deunobicho.online/prova/..."
  }
}

The sha256 in meta lets consumers verify integrity against /api/prova/{id}. This is not decorative — journalists actually verify it.

OpenAPI 3.1 spec

The full spec lives at https://deunobicho.online/api-publica/openapi.json. A minimal extract:

openapi: 3.1.0
info:
  title: deunobicho Public API
  version: 1.0.0
  description: Read-only Brazilian lottery data
  contact:
    name: Athos Alexandre
    url: https://deunobicho.online
  license:
    name: CC BY 4.0
servers:
  - url: https://deunobicho.online/api

paths:
  /loterias/federal/{date}:
    get:
      summary: Federal lottery result for a specific date
      parameters:
        - name: date
          in: path
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Result found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederalResult'
        '404':
          description: No draw on that date

You can drop this into Postman, Swagger UI, or any codegen tool (openapi-generator, orval) and get typed clients in minutes.

Integration examples

JavaScript / TypeScript (with `fetch`)

type FederalResult = {
  meta: { generated_at: string; sha256: string };
  data: {
    concurso: number;
    data_extracao: string;
    premios: { ordem: number; numero: string; valor: number }[];
  };
  links: { self: string; evidence: string };
};

async function todayFederal(): Promise<FederalResult> {
  const res = await fetch(
    'https://deunobicho.online/api/loterias/federal/hoje',
    { next: { revalidate: 60 } }
  );
  return res.json();
}

Python (with `httpx`)

import httpx

def federal_result(date: str) -> dict:
    r = httpx.get(f'https://deunobicho.online/api/loterias/federal/{date}')
    r.raise_for_status()
    return r.json()

# Fetch and validate integrity
result = federal_result('2026-09-18')
assert result['meta']['sha256'] is not None

Bash / curl (one-liner for scripts)

curl -s https://deunobicho.online/api/loterias/federal/hoje \
  | jq -r '.data.premios[] | "\(.ordem)º prêmio: \(.numero)"'

Output:

1º prêmio: 58437
2º prêmio: 90012
3º prêmio: 21789
4º prêmio: 66412
5º prêmio: 03875

Use cases in the wild

Users have already built:

A WhatsApp bot (/bicho) that returns the latest draw when messaged
A Home Assistant integration that announces results at 19:05 daily via Alexa
A research notebook correlating dream-symbol frequency with cultural events
A journalism project verifying alleged bicho manipulation claims
A university thesis on the 134-year statistical properties of the jogo do bicho

The point is: giving away read-only public data unlocks a long tail of creative uses that no proprietary API would ever discover.

Rate limits and terms

Free tier: 300 req/min per IP, 100k req/day
License: CC BY 4.0 (attribution required, commercial use OK)
Attribution: "Data via deunobicho.online" or a link back
No auth needed for the free tier
No SLA — best-effort, but historical uptime is ~99.9% (Vercel edge)

If your project needs guarantees, a dedicated tier with SLA is available on request via contact@deunobicho.online.

What is intentionally out of scope

Placing bets. This is a data API, not a betting API. The portal is editorial, not operational.
Predictions / "hot numbers". We do not endorse or ship predictive endpoints. Every draw is (assumed) independent.
User accounts, saved tickets, personalization. Free tier is stateless.

Roadmap

WebSocket / SSE endpoint for real-time result push
GraphQL variant (community request, low priority)
Historical bulk exports (parquet, per-year)
Multi-language docs (currently EN + PT-BR)

Feature requests welcome via GitHub — the spec repo will be open-sourced shortly.

Using SHA256 to Build Trustworthy Data Portals in Brazil

Vou Embarcar — Mon, 21 Sep 2026 19:45:46 +0000

Data portals in emerging markets face a specific credibility problem: how do you prove that the data you display was not silently altered after publication?

This matters more than it sounds. Editorial portals covering lottery results, election counts, or public dataset feeds in Brazil are frequently accused (rightly or not) of tampering. The typical defense — "trust us, we did not change anything" — is not defensible in 2026.

I run deunobicho.online, a portal covering Brazilian lottery results, and I want to share how we solved this with a very old, very boring cryptographic primitive: SHA256 content hashing with public evidence pages.

The problem in concrete terms

Every day, the portal publishes ~7 lottery result batches. Each batch has:

A publication timestamp
A source (usually a screenshot of the official state lottery broadcast)
A tabular payload (numbers, prizes, groups)

If a user visits at 15:30, sees result X, and later returns at 20:00 to find result Y at the same URL, they have a legitimate reason to distrust the portal.

The naive fix is "just don't change results." Real editorial life is messier: typos happen, source corrections happen, timezones are hard. The correct fix is: make every change publicly auditable.

The SHA256 evidence pattern

Here is the pattern we ship:

Every published resource has a canonical JSON representation.
At publish time, we compute sha256(canonical_json) and store it alongside the resource.
We publish a public evidence page at /prova/<result-id> that displays:
- The raw canonical JSON
- The SHA256 hash
- The timestamp
- A link to the source (screenshot / official broadcast)
The evidence page is served with Cache-Control: public, immutable. It cannot be modified without changing the URL.
If we ever correct a result, we publish a new evidence page with a new hash and link both old and new from an audit log.

The user experience: any reader can, at any time, verify that the number they saw on Twitter matches the hash on the portal.

Implementation in Next.js 16 (App Router)

Here is the minimal shape of the API route:

// src/app/api/prova/[id]/route.ts
import { createHash } from 'node:crypto';
import { NextResponse } from 'next/server';

export const dynamic = 'force-static';
export const revalidate = false; // never revalidate — evidence is immutable

interface Evidence {
  id: string;
  published_at: string;   // ISO 8601 UTC
  source_url: string;     // screenshot / broadcast
  payload: Record<string, unknown>;
  hash: string;           // sha256 hex
}

function canonicalize(obj: unknown): string {
  // stable JSON: sorted keys, no whitespace
  if (obj === null || typeof obj !== 'object') {
    return JSON.stringify(obj);
  }
  if (Array.isArray(obj)) {
    return '[' + obj.map(canonicalize).join(',') + ']';
  }
  const keys = Object.keys(obj as Record<string, unknown>).sort();
  return '{' + keys.map(k =>
    JSON.stringify(k) + ':' + canonicalize((obj as Record<string, unknown>)[k])
  ).join(',') + '}';
}

export async function GET(
  _req: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const record = await loadRecord(id); // from DB
  const canonical = canonicalize(record.payload);
  const hash = createHash('sha256').update(canonical).digest('hex');

  const evidence: Evidence = {
    id: record.id,
    published_at: record.published_at,
    source_url: record.source_url,
    payload: record.payload,
    hash,
  };

  return NextResponse.json(evidence, {
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      'Cache-Control': 'public, max-age=31536000, immutable',
    },
  });
}

The key detail is canonical JSON. JSON.stringify on an object with keys in different orders yields different bytes, hence different SHA256. If you skip canonicalization, your hash is unreliable.

Verifying from the client (curl or browser)

A reader can verify independently:

curl -s https://deunobicho.online/api/prova/2026-09-18-federal-1 \
  | jq -c '.payload' \
  | shasum -a 256

The output should match the hash field in the same JSON. If it doesn't, someone (us or an intermediate cache) tampered with the payload.

This is trivially scriptable. We publish a verify snippet on the portal itself, so non-technical journalists can copy-paste and confirm.

Why not blockchain?

We get this question every week. The short answer: you do not need a blockchain to prove content integrity. A blockchain proves ordering and consensus — properties we do not need. SHA256 + public URL + Wayback Machine snapshots gives:

Content integrity: SHA256 on canonical JSON
Temporal proof: Wayback Machine crawls (https://web.archive.org/web/*/deunobicho.online/prova/*) — free, no gas fees, higher trust than most L2s
Public verifiability: any reader can curl | shasum in 3 seconds

A blockchain adds cost, latency, and complexity without adding trust value for this use case. We looked at OpenTimestamps for a while (it is free and adds a real timestamping anchor to Bitcoin), and we may add it as a secondary anchor later. But the primary evidence is the SHA256 + immutable URL.

What we learned in production

Six months in, three lessons:

1. Immutable URLs are contagious. Once we published /prova/<id> pages, journalists started linking directly to them from their articles. This is now our #1 referrer source. Reader trust compounded.

2. Canonical JSON is harder than it looks. We had a bug where dates were serialized as "2026-09-18T00:00:00.000Z" in one code path and "2026-09-18T00:00:00Z" in another. Same date, different bytes, different hash. Fix: normalize all dates to millisecond-precision UTC ISO 8601 at write time.

3. Corrections happen. Plan for them. We had to correct one result in six months. The audit trail worked: we published /prova/<id>-v2 with a new hash, added a superseded_by field to the old evidence page, and posted a public correction note. Zero credibility damage — the transparency actually increased trust.

Reading the source

The full implementation of /prova/<id> is open on the portal itself — visit any recent result and scroll down to the "Prova SHA256" footer. The API is documented at deunobicho.online/api-publica.

For portal maintainers building similar infra in other regulated / high-scrutiny domains (elections, public health data, financial disclosures), the same pattern generalizes:

Canonical JSON of the payload
SHA256 at publish time
Immutable URL for the evidence
Wayback Machine as temporal anchor
Public audit log for corrections

That is it. No blockchain, no proprietary vendor, no trust in the portal itself — just cryptographic integrity readers can verify with shasum -a 256.

Athos Alexandre is the founder of deunobicho.online, an editorial portal covering Brazilian lottery data. He writes about data transparency, Next.js, and building trustworthy public interfaces in high-scrutiny domains.

Using SHA256 to Build Trustworthy Data Portals in Brazil

Vou Embarcar — Mon, 21 Sep 2026 19:01:16 +0000

Data portals in emerging markets face a specific credibility problem: how do you prove that the data you display was not silently altered after publication?

The problem in concrete terms

Every day, the portal publishes ~7 lottery result batches. Each batch has:

A publication timestamp
A source (usually a screenshot of the official state lottery broadcast)
A tabular payload (numbers, prizes, groups)

If a user visits at 15:30, sees result X, and later returns at 20:00 to find result Y at the same URL, they have a legitimate reason to distrust the portal.

The SHA256 evidence pattern

Here is the pattern we ship:

Every published resource has a canonical JSON representation.
At publish time, we compute sha256(canonical_json) and store it alongside the resource.
We publish a public evidence page at /prova/<result-id> that displays:
- The raw canonical JSON
- The SHA256 hash
- The timestamp
- A link to the source (screenshot / official broadcast)
The evidence page is served with Cache-Control: public, immutable. It cannot be modified without changing the URL.
If we ever correct a result, we publish a new evidence page with a new hash and link both old and new from an audit log.

The user experience: any reader can, at any time, verify that the number they saw on Twitter matches the hash on the portal.

Implementation in Next.js 16 (App Router)

Here is the minimal shape of the API route:

// src/app/api/prova/[id]/route.ts
import { createHash } from 'node:crypto';
import { NextResponse } from 'next/server';

export const dynamic = 'force-static';
export const revalidate = false; // never revalidate — evidence is immutable

interface Evidence {
  id: string;
  published_at: string;   // ISO 8601 UTC
  source_url: string;     // screenshot / broadcast
  payload: Record<string, unknown>;
  hash: string;           // sha256 hex
}

function canonicalize(obj: unknown): string {
  // stable JSON: sorted keys, no whitespace
  if (obj === null || typeof obj !== 'object') {
    return JSON.stringify(obj);
  }
  if (Array.isArray(obj)) {
    return '[' + obj.map(canonicalize).join(',') + ']';
  }
  const keys = Object.keys(obj as Record<string, unknown>).sort();
  return '{' + keys.map(k =>
    JSON.stringify(k) + ':' + canonicalize((obj as Record<string, unknown>)[k])
  ).join(',') + '}';
}

export async function GET(
  _req: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const record = await loadRecord(id); // from DB
  const canonical = canonicalize(record.payload);
  const hash = createHash('sha256').update(canonical).digest('hex');

  const evidence: Evidence = {
    id: record.id,
    published_at: record.published_at,
    source_url: record.source_url,
    payload: record.payload,
    hash,
  };

  return NextResponse.json(evidence, {
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      'Cache-Control': 'public, max-age=31536000, immutable',
    },
  });
}

Verifying from the client (curl or browser)

A reader can verify independently:

curl -s https://deunobicho.online/api/prova/2026-09-18-federal-1 \
  | jq -c '.payload' \
  | shasum -a 256

The output should match the hash field in the same JSON. If it doesn't, someone (us or an intermediate cache) tampered with the payload.

This is trivially scriptable. We publish a verify snippet on the portal itself, so non-technical journalists can copy-paste and confirm.

Why not blockchain?

Content integrity: SHA256 on canonical JSON
Temporal proof: Wayback Machine crawls (https://web.archive.org/web/*/deunobicho.online/prova/*) — free, no gas fees, higher trust than most L2s
Public verifiability: any reader can curl | shasum in 3 seconds

What we learned in production

Six months in, three lessons:

Reading the source

The full implementation of /prova/<id> is open on the portal itself — visit any recent result and scroll down to the "Prova SHA256" footer. The API is documented at deunobicho.online/api-publica.

For portal maintainers building similar infra in other regulated / high-scrutiny domains (elections, public health data, financial disclosures), the same pattern generalizes:

Canonical JSON of the payload
SHA256 at publish time
Immutable URL for the evidence
Wayback Machine as temporal anchor
Public audit log for corrections

That is it. No blockchain, no proprietary vendor, no trust in the portal itself — just cryptographic integrity readers can verify with shasum -a 256.

DEV Community: Vou Embarcar

Public API for Brazilian Lottery Data: OpenAPI Spec and Use Cases

What the API covers

Design decisions

1. Read-only, no auth for the free tier

2. JSON only, no XML, no SOAP

3. force-static for archive endpoints

4. Last-Modified and ETag on hot endpoints

5. Consistent envelope

OpenAPI 3.1 spec

Integration examples

JavaScript / TypeScript (with fetch)

Python (with httpx)

Bash / curl (one-liner for scripts)

Use cases in the wild

Rate limits and terms

What is intentionally out of scope

Roadmap

Further reading

Using SHA256 to Build Trustworthy Data Portals in Brazil

The problem in concrete terms

The SHA256 evidence pattern

Implementation in Next.js 16 (App Router)

Verifying from the client (curl or browser)

Why not blockchain?

What we learned in production

Reading the source

Using SHA256 to Build Trustworthy Data Portals in Brazil

The problem in concrete terms

The SHA256 evidence pattern

Implementation in Next.js 16 (App Router)

Verifying from the client (curl or browser)

Why not blockchain?

What we learned in production

Reading the source

3. `force-static` for archive endpoints

4. `Last-Modified` and `ETag` on hot endpoints

JavaScript / TypeScript (with `fetch`)

Python (with `httpx`)