Înveți structura o singură dată.

Aceleași reguli se aplică peste tot, așa că le înveți o singură dată.

Învelișul

Un payload este întotdeauna sub data. Listele adaugă links (URL-uri cu cursor) și meta.

{
  "data": [ … ],
  "links": { "first": null, "last": null, "prev": null, "next": "https://api.lottevo.com/v1/lotteries?cursor=eyJ…" },
  "meta": { "path": "https://api.lottevo.com/v1/lotteries", "per_page": 25, "next_cursor": "eyJ…", "prev_cursor": null }
}

Paginarea se face cu cursor

O pagină are 25 de elemente, iar per_page poate doar să micșoreze o pagină — niciodată să o mărească. Urmează links.next până devine null.

Paginarea cu offset nu este oferită intenționat. Lista de rezultate primește mereu înregistrări noi, iar o pagină cu offset se deplasează sub tine pe măsură ce sosesc extrageri noi: pagina 2 ar repeta rânduri pe care ți le-a dat deja pagina 1.

Filtrare, sortare, includere

?filter[country]=RO&filter[from]=2026-01-01&sort=-drawn_at&include=prizes

Listele se separă prin virgulă: filter[lottery]=RO-001,HU-001. Pentru sortare descrescătoare pui - în față. Relațiile se includ doar la cerere, pentru că o extragere poate avea o duzină de categorii de premii sau chiar mai multe.

Un filtru, o sortare sau o includere nedeclarată primește un 422 care numește ce este disponibil, în loc să fie ignorată tacit — o omitere tacită ar răspunde cu mult mai multe rânduri decât ai cerut.

Cache

Fiecare citire reușită are un ETag puternic. Trimite-l înapoi ca If-None-Match, iar o interogare care nu a găsit nicio schimbare te costă un 304 fără corp:

curl https://api.lottevo.com/v1/draws \
  -H 'X-Api-Key: …' \
  -H 'If-None-Match: "aad0ecbef9acb3804c1db3083346d3c4"'

Un 304 contează totuși ca o cerere din cota ta. Economisește lățime de bandă și parsare, nu cotă.

Headerele limitei de cereri

Fiecare răspuns dat după autentificare le conține, ca să-ți poți regla ritmul în loc să descoperi limita fiind refuzat:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-Quota-Limit: 25000
X-Quota-Remaining: 24873
X-Quota-Reset: 2026-09-21T00:00:00+00:00

X-Quota-Limit și X-Quota-Remaining lipsesc la un plan necontorizat. Fereastra zilnică se resetează la miezul nopții UTC, deci nu depinde de locul din care faci apelul. Două răspunsuri date după autentificare nu au niciunul dintre ele: un 402 subscription_required și un 429 rate_limit_exceeded, care are în schimb Retry-After.

Fiecare răspuns dat după autentificare are și un X-Request-Id, care identifică acel apel în Jurnalul cererilor și într-o cerere de suport. Un 401 sau un 403 origin_not_allowed răspunde înainte ca cheia să fie acceptată, așa că nu are nici aceste headere, nici ID de cerere. Vezi Erori.

Limba

Accept-Language este respectat. Numele jocurilor, descrierile programelor și mesajele de eroare vin în limba negociată, iar răspunsul are Content-Language, cu Accept-Language adăugat la Vary.

Valori ușor de interpretat greșit

• Sumele sunt șiruri de caractere, nu numere JSON. Sunt decimal(20,6), iar un float le-ar rotunji. Formatează pornind de la șir.
• null nu înseamnă zero. Null înseamnă că nu a fost raportată nicio valoare; zero înseamnă că valoarea a fost zero.
• Un joc multinațional are country: null — așa e modelul, nu sunt date lipsă. Folosește include=availability ca să vezi unde se joacă.
• bonus_numbers poate conține litere, nu doar numere. Unele jocuri extrag o literă.
• numbers e în ordinea extragerii acolo unde o putem citi; sorted_numbers e mereu crescător. Mulți operatori publică rezultatul sortat, și atunci și numbers e sortat. Un rezultat recuperat ulterior din arhiva operatorului poate fi sortat chiar dacă rezultatele live ale aceluiași joc nu sunt. Compară rezultatele pe sorted_numbers.
• multiplier e exact, nu mereu întreg. Un multiplicator de 1.5X, ca la BC Keno, apare 1.5; cei întregi apar 2, 3. multiplier e 0 când jocul n-a extras niciun multiplicator.
• Un rezultat poate fi provizoriu. Unele rezultate sunt citite în direct din transmisia TV a extragerii, cu câteva minute înainte ca operatorul să le publice, și au provisional: true. Sosesc ca draw.published, la fel ca oricare altul. Când publicarea operatorului se potrivește, provisional devine false, confirmed_at primește data confirmării și se trimite draw.confirmed; când nu se potrivește, numerele sunt corectate și se trimite draw.revised. Un rezultat care n-a fost publicat în direct are confirmed_at: null.

Sume în euro și în dolari

Fiecare extragere are sumele convertite în euro și în dolari americani (jackpot_amount_eur, jackpot_amount_usd, next_jackpot_amount_eur, next_jackpot_amount_usd), la cursurile oficiale din ziua extragerii, iar cursurile folosite sunt în exchange_rate. Jackpotul anunțat al unui joc (upcoming.jackpot) are amount_eur și amount_usd la cursul zilei.

• currency ține de extragere. Rezultatele românești dinainte de 2005 sunt în lei vechi (ROL).
• O sumă convertită e null când suma e null sau zero, ori când niciun curs oficial nu acoperă ziua respectivă. Înainte de 1999 se cunoaște doar partea în care e deja suma (euro sau dolari).
• O extragere de azi poate fi convertită întâi la cursul din ziua precedentă și trece pe cursul zilei ei după ce acesta e publicat.

Cursurile de schimb provin de la Banca Centrală Europeană și de la băncile centrale naționale, inclusiv Banco Central de Chile, pentru pesoul chilian.