# Felho API

> Magyar céginformációs és domain API. Cégjegyzéki adatok, tulajdonosok, tisztségviselők, közzétett pénzügyi beszámolók és WHOIS/RDAP lekérdezés.

## Alapok

- Alap URL: `https://felho.hu/api/v1`
- Hitelesítés: `Authorization: Bearer flh_live_…`
- Korlát: 60 kérés/perc kulcsonként (`X-RateLimit-Remaining`)
- Válasz: JSON, UTF-8

## Fontos tudnivalók

- A hiányzó adat `null`, nem 0 és nem üres sztring. Egy beszámolót be nem nyújtó cég nem nulla árbevételű cég.
- A WHOIS `registered` mezője háromértékű: `true` foglalt, `false` igazoltan szabad, `null` sikertelen lekérdezés. A `null` **soha** nem jelent szabad domaint.
- Több nyilvántartó (.hu, .de, .at, .eu, .be, .nl) nem teszi közzé a lejárati dátumot. Ilyenkor `expiryDate` hiányzik; az `estimatedExpiry` a regisztráció évfordulójából számolt **becslés**, nem nyilvántartói adat.
- A `verificationScore` és a `riskScore` a Felho saját származtatott mutatói, nem hitelminősítői vagy hatósági értékek.
- A bankszámlákhoz tartozó `bank` mező a számlaszám első három jegyéből származik, és `null`, ha a kód nem azonosítható biztosan.

## Végpontok

### GET /companies

Az indexelt cégek lapozható listája. Szűrhető szabadszavas kereséssel, városra és iparágra. A keresés a cégnévre, teljes névre, adószámra, cégjegyzékszámra és az ügyvezető nevére illeszkedik.

| Paraméter | Típus | Leírás |
| --- | --- | --- |
| `q` | string | Keresőkifejezés. Ez váltja ki a külön kereső végpontot. |
| `city` | string | Város slug, pl. budapest. |
| `industry` | string | Iparág slug, ahogy az /iparag útvonalban szerepel. |
| `limit` | integer | Találatok száma, max 100 (alap: 25). |
| `offset` | integer | Hányadik találattól (alap: 0). |

```json
{
  "data": [
    {
      "id": "optifon-kft",
      "name": "OPTIFON Kft.",
      "taxNumber": "23860276-2-19",
      "registrationNumber": "19-09-515125",
      "status": "active",
      "industry": "Információs, híradástechnikai termék kiskereskedelme",
      "teaorCode": "4740",
      "city": "Veszprém",
      "verificationScore": 94,
      "riskLevel": "low",
      "url": "https://felho.hu/ceg/optifon-kft"
    }
  ],
  "pagination": { "total": 12, "limit": 25, "offset": 0, "hasMore": false }
}
```

### GET /companies/{id}

Minden nyilvános adat egy cégről: tulajdonosok, tisztségviselők (anyja nevével és lakcímével, ahogy a cégjegyzékben szerepel), közzétett pénzügyi évek, bankszámlák és megfelelőségi jelzők. A hiányzó mezők null értékkel szerepelnek — nem becsüljük meg őket.

```json
{
  "data": {
    "id": "optifon-kft",
    "name": "OPTIFON Kft.",
    "legalName": "OPTIFON Kereskedelmi és Szolgáltató Korlátolt Felelősségű Társaság",
    "officers": [
      { "name": "Nagyőszi Norbert", "role": "managingDirector",
        "motherName": "Kozma Margit", "residence": "8200 Veszprém, Mester utca 34." }
    ],
    "financials": [
      { "year": 2025, "totalRevenue": 801307000, "profitAfterTax": 248688000,
        "equity": 473742000, "employees": 38 }
    ],
    "bankAccounts": [
      { "number": "12082104-01982083-00100000", "opened": "2024-06-05",
        "bank": "Raiffeisen Bank", "status": "active" }
    ]
  }
}
```

### GET /whois/{domain}

WHOIS/RDAP lekérdezés. A `registered` mező háromértékű: `true` foglalt, `false` igazoltan szabad, `null` a lekérdezés nem sikerült. A `null` soha nem jelent szabad domaint. Több nyilvántartó (.hu, .de, .at, .eu) nem teszi közzé a lejárati dátumot — ilyenkor `expiryDate` üres, és `estimatedExpiry` a regisztráció évfordulójából számolt becslés.

```json
{
  "domain": "felho.hu",
  "registered": true,
  "registrar": "Rackhost Zrt.",
  "createdDate": "2015-03-24",
  "expiryDate": null,
  "estimatedExpiry": "2027-03-24",
  "nameservers": ["ns1.rackhost.hu", "ns2.rackhost.hu"],
  "source": "whois",
  "note": "A .hu nyilvántartó nem teszi közzé a lejárati dátumot…"
}
```

## Hibakódok

| HTTP | Kód | Mikor |
| --- | --- | --- |
| 401 | `unauthorized` | Hiányzó, visszavont vagy érvénytelen kulcs. |
| 404 | `not_found` | Nincs ilyen azonosítójú rekord. |
| 429 | `rate_limit_exceeded` | Túllépted a percenkénti 60 kérést. Az X-RateLimit-Remaining fejléc mutatja a maradékot. |
| 503 | `service_unavailable` | A háttérszolgáltatás nem elérhető — a kérés megismételhető. |

## Kapcsolódó oldalak

- https://felho.hu/dokumentacio
- https://felho.hu/cegkereso
- https://felho.hu/toplista
- https://felho.hu/sitemap.xml