Documentația API Hei!Local

API-ul public Hei!Local îți dă acces programatic la aceeași căutare ca pe site: produse de pe magazinele .ro și conținut (pagini, firme, servicii) de pe site-uri .ro.

1. Cheia API

1. Intră în contul tău Hei!Local, la Conectare AI.
2. Activează planul Gratuit (accepți termenii API).
3. Apasă Generează. Cheia (hl_…) e afișată o singură dată: salveaz-o. O poți revoca sau regenera oricând din același loc.

Trimite cheia în antetul X-API-Key (sau Authorization: Bearer hl_…). Nu o pune în URL și nu o publica în cod sau în aplicații din browser.

2. Endpoint-uri

Moduri

Corpul cererii (JSON)

3. Exemple

curl

curl -X POST "https://heilocal.ro/api/v1/products/search?mode=processed" \
  -H "X-API-Key: hl_cheia_ta" \
  -H "Content-Type: application/json" \
  -d '{"query": "geacă de iarnă bărbați", "limit": 5, "price_max": 400}'

Python

import requests

r = requests.post(
    "https://heilocal.ro/api/v1/content/search",
    params={"mode": "raw"},
    headers={"X-API-Key": "hl_cheia_ta"},
    json={"query": "instalator sanitar Cluj", "limit": 5},
    timeout=60,
)
r.raise_for_status()
for item in r.json()["results"]:
    print(item["title"], item["url"])

Răspuns (produse)

{
  "success": true,
  "mode": "processed",
  "query": "geacă de iarnă bărbați",
  "offset": 0,
  "limit": 5,
  "count": 5,
  "results": [
    {
      "title": "Geacă bărbați de iarnă îmblănită",
      "url": "https://magazin.ro/produs/...",
      "domain": "magazin.ro",
      "ai_category": "Imbracaminte",
      "image": "https://heilocal.ro/api/img/…?w=800",
      "score": 0.83
    }
  ],
  "credits": {"charged": 5, "today": {"used": 12, "limit": 100}, "month": {"used": 40, "limit": 1000}}
}

La conținut, fiecare rezultat are title, url, domain, category, snippet (un rezumat scurt, max. 300 de caractere) și score. În modul processed, răspunsul poate avea și low_confidence: true (rezultate aproximative) sau relevance_gap (rezultatele de sus nu respectă o culoare sau un atribut cerut).

4. Prețuri

price_min și price_max sunt doar filtre, în ambele moduri. În modul processed se aplică și prețul înțeles din text („sub 500 de lei”); când există ambele, se păstrează intervalul cel mai strâns.

• Doar aproximativ 73% din produse au un preț extras. Produsele fără preț nu apar când folosești un filtru de preț.
• Filtrul folosește ultimul preț văzut de Hei!Local, nu prețul de azi: la circa 1 din 6 produse prețul s-a schimbat de atunci pe site-ul magazinului.

5. Limite și credite (planul Gratuit)

Se taxează doar căutările reușite. Ziua și luna se socotesc în UTC. Fiecare răspuns are antetele X-RateLimit-Limit (creditele pe zi), X-RateLimit-Remaining și X-RateLimit-Reset (momentul resetării zilnice, în secunde Unix). Consumul pe zile îl vezi în Conectare AI.

Căutările făcute de asistentul tău AI prin serverul MCP cer același plan activ și consumă din aceleași credite (5 per căutare).

6. Erori

Corpul unei erori: {"success": false, "error": "…"}.

7. Reguli

Folosirea API-ului e supusă termenilor API. Extragerea sistematică a catalogului și redistribuirea datelor sunt interzise. Pentru volume mai mari, scrie-ne la hei@heilocal.ro.