Alimenta Data / versiunea 1

Date de preț, cu sursa la vedere.

Un API de citire pentru integrări aprobate. Primești prețurile publicate în catalogul ANRE, contextul observației și plafoanele naționale, fără să confunzi ora preluării cu ora schimbării la pompă.

Începe integrarea Descarcă schema OpenAPI

Acces cu aprobare manualăNu există înregistrare automată pentru chei. Verificăm solicitantul, scopul și condițiile de reutilizare înainte de a oferi acces extern.

01 / Pornire

O cheie pentru fiecare integrare.

Cheia se emite manual și se afișează o singură dată. Trimite-o în headerul Authorization prin HTTPS, din serverul tău. Nu o pune în aplicația mobilă, JavaScript public, URL, loguri sau capturi de ecran.

GEThttps://alimenta.md/api/v1/stations

curl --request GET \
  --header "Authorization: Bearer $ALIMENTA_API_KEY" \
  'https://alimenta.md/api/v1/stations?fuel=diesel&limit=50&page=1'

Exemplul folosește o variabilă de mediu; nu conține o cheie reală. API-ul este numai pentru citire și nu are CORS destinat apelurilor directe din browser.

02 / Cerere

Alege exact datele necesare.

Endpointul întoarce doar stații active în sursa ANRE. Fără filtre primești toate carburantele disponibile pentru fiecare stație, în pagini ordonate stabil după ID.

Parametru	Valori	Ce face
`fuel`	`gasoline95`, `diesel`, `lpg`	Returnează stațiile cu preț publicat pentru carburantul ales și numai acel preț în obiectul `prices`.
`district`	Denumire exactă, de exemplu `Chișinău`	Filtrează după raionul/localitatea din catalog. Codifică textul în URL.
`page`	1–10.000; implicit 1	Alege pagina de rezultate.
`limit`	1–100; implicit 50	Alege câte stații apar într-o pagină.

Folosește pagination.has_next pentru a continua. Parametrii dublați, valorile invalide și paginarea în afara intervalului primesc 400.

03 / Răspuns

Prețul și contextul lui rămân împreună.

Un răspuns 200 are data (stațiile), pagination, source și national_price_caps. Când ANRE publică un plafon pentru o dată ulterioară celei din e-Carburanți, apare separat published_price_caps, cu data publicării și data aplicării. Fragmentul de mai jos arată forma câmpurilor; valorile sunt strict ilustrative, nu prețuri de azi.

{
  "data": [{
    "id": "anre-exemplu",
    "name": "Stație exemplu",
    "operator": "Operator exemplu",
    "address": "Adresă exemplu",
    "district": "Chișinău",
    "latitude": 47.0,
    "longitude": 28.8,
    "prices": {
      "gasoline95": {
        "value": 33.49,
        "currency": "MDL",
        "unit": "litre",
        "source": "ANRE e-Carburanți",
        "source_url": "https://api.ecarburanti.anre.md/public/",
        "observed_at": "2026-09-23T12:00:00Z",
        "effective_at": null,
        "pump_verified": false
      }
    }
  }],
  "pagination": {"page": 1, "limit": 50, "total": 1, "has_next": false},
  "source": {
    "name": "ANRE e-Carburanți",
    "url": "https://api.ecarburanti.anre.md/public/",
    "observed_at": "2026-09-23T12:00:00Z",
    "source_updated_at": null,
    "note": "Ora schimbării efective la pompă nu este publicată."
  },
  "national_price_caps": {
    "effective_date": "2026-09-23",
    "prices": {"gasoline95": 34.04, "diesel": 36.63},
    "currency": "MDL",
    "unit": "l"
  }
}

prices.*.value: Preț publicat, în MDL per litru. Lipsa unui carburant din prices înseamnă că nu avem preț publicat; nu înseamnă stoc zero.
source.observed_at: Momentul UTC în care Alimenta a preluat ultima observație disponibilă din sursă. Verifică acest câmp pentru prospețime.
effective_at / pump_verified: null și false arată că ora efectivă și confirmarea la pompă nu sunt disponibile.
national_price_caps / published_price_caps: Primul este plafonul din e-Carburanți; al doilea, când apare, este anunțul mai nou de pe pagina ANRE. Fiecare are data sa de aplicare. Niciunul nu este un preț confirmat la pompă.

04 / Utilizare

Limitele sunt per cheie.

La emitere, proprietarul alege maximum de cereri pe minut și pe zi. Valorile pilot inițiale din board sunt 60/minut și 10.000/zi; pot fi schimbate pentru fiecare integrare. Minutele și zilele se calculează în UTC, iar ziua se resetează la 00:00 UTC.

X-RateLimit-Remaining-Minute: 42X-RateLimit-Remaining-Day: 9982

Aceste headere apar la răspunsurile reușite și la unele erori de validare după autentificare. La 429, headerul Retry-After indică secundele de așteptare până la următoarea fereastră.

05 / Erori

Răspunsuri pe care le poți trata.

Cod	Înseamnă	Ce faci
`200`	Cererea a reușit.	Citește `source.observed_at` și `pagination.has_next`.
`400`	Filtru sau paginare invalidă.	Corectează parametrii înainte de repetare.
`401`	Cheia lipsește, este invalidă sau a fost revocată.	Verifică headerul; cere o cheie nouă dacă accesul a fost revocat.
`429`	Ai atins limita pe minut sau pe zi.	Așteaptă numărul de secunde din `Retry-After`; nu repeta imediat.

La indisponibilitatea sursei ANRE, API-ul poate arăta ultima observație validă. Nu deduce actualitatea din codul 200; verifică ora observației.

06 / Proveniență

Ce nu promite acest API.

În v1 sunt incluse doar prețurile ANRE pentru benzină 95, motorină și GPL. Nu exportăm recenzii Google, disponibilitate de stoc, încărcătoare electrice, prețuri POS ori tarife confirmate la minut. Prețurile din sursă pot întârzia; observed_at nu este ora schimbării prețului la pompă.

Cheia permite citirea datelor, nu acordă automat drept de redistribuire comercială. Condițiile de folosire și atribuirea sursei se stabilesc pentru fiecare partener înainte de emitere. Pentru detalii tehnice, poți folosi și schema OpenAPI 3.1.