Companies PiTS s.r.o. Companies PiTS s.r.o.
REST API

Načítání ekonomických subjektů z registru ARES

Jednoduché REST API pro vyhledávání firem podle názvu a načítání detailu firmy podle IČO. Komunikace probíhá výhradně přes HTTPS, odpovědi jsou ve formátu JSON.

01

Autentizace

Všechny endpointy vyžadují platný přístupový token, který se předává v hlavičce Authorization schématem Bearer. Token vám vystavíme po dohodě. 

Authorization: Bearer <váš-access-token>
02

Endpointy

Base URL https://companies.pits.cz
GET /api/ping

Ověření dostupnosti API a platnosti přístupového tokenu.

Odpověď

{"message": "pong"}
GET /api/ares/companies

Našeptávač firem podle názvu — vrátí seznam subjektů odpovídajících dotazu.

Query parametry

  • query — povinné, min. 2 znaky
  • limit — volitelné, výchozí 10, max. 25

Příklad

GET /api/ares/companies?query=pits&limit=5
Authorization: Bearer <váš-access-token>

Odpověď

{
  "results": [
    {
      "companyId": "12345678",
      "companyName": "PiTS s.r.o.",
      "address": "Praha 1, 110 00"
    }
  ],
  "count": 1
}
GET /api/ares/lookup název i IČO

Sjednocený lookup — pokud je dotaz čistě číselný (1–8 číslic), server jej interpretuje jako IČO a vrátí detail v autocomplete-tvaru; jinak provede našeptávač podle názvu. Výsledek je vždy stejný JSON, klient nemusí nic detekovat.

Query parametry

  • query — povinné, min. 2 znaky (číslo = IČO, jinak název)
  • limit — volitelné, výchozí 10, max. 25 (ignorováno při IČO)

Příklad – název

GET /api/ares/lookup?query=pits
Authorization: Bearer <váš-access-token>

Příklad – IČO

GET /api/ares/lookup?query=12345678
Authorization: Bearer <váš-access-token>

Odpověď

{
  "results": [
    {
      "companyId": "12345678",
      "companyName": "PiTS s.r.o.",
      "address": "Praha 1, 110 00"
    }
  ],
  "count": 1
}

Když IČO neexistuje, vrátí se { "results": [], "count": 0 } — žádné 404 v happy path.

GET /api/ares/companies/{companyId}

Detail firmy podle IČO. Hodnota companyId je IČO o délce 1–8 číslic (kratší hodnoty se automaticky doplní nulami zleva).

Příklad

GET /api/ares/companies/12345678
Authorization: Bearer <váš-access-token>

Odpověď

{
  "companyId": "12345678",
  "taxId": "CZ12345678",
  "companyName": "PiTS s.r.o.",
  "legalForm": "Společnost s ručením omezeným",
  "address": {
    "full": "Ulice 123/4, 110 00 Praha 1",
    "street": "Ulice",
    "houseNumber": "123/4",
    "city": "Praha 1",
    "postalCode": "110 00",
    "countryCode": "CZ"
  },
  "registeredAt": "2010-01-01",
  "dissolvedAt": null,
  "primaryNaceCode": "62010",
  "syncedAt": "2026-05-20T08:00:00+00:00"
}
03

Limity požadavků

Každý požadavek je počítán proti rate limitu zvlášť pro vyhledávání a pro detail firmy. Aktuální stav vrací API v hlavičkách odpovědi:

  • X-RateLimit-Limit — celkový limit
  • X-RateLimit-Remaining — zbývající počet požadavků
  • X-RateLimit-Reset — unix timestamp obnovení limitu

Při překročení limitu API vrací stav 429 Too Many Requests.

04

Chybové stavy

  • 400 — neplatný vstup (např. krátký dotaz pro vyhledávání)
  • 401 — chybějící nebo neplatný přístupový token
  • 404 — firma nebyla v registru ARES nalezena
  • 429 — překročen rate limit
  • 503 — registr ARES je dočasně nedostupný

Zájem o využití služby

Pokud má vaše firma zájem tuto službu používat, kontaktujte nás na pits.cz.

Ochrana osobních údajů

Informace o zpracování osobních údajů najdete na pits.cz/ochrana-osobnich-udaju.