Dokumentace
REST API s OpenAPI popisem, MCP server pro AI agenty a webhooky pro hlídání změn. Vše pod jedním klíčem.
Autentizace
Klíč získáte registrací nebo POST /api/v1/auth/register. Posílejte ho v hlavičce Authorization: Bearer ap_live_… (nebo X-Api-Key). Odpovědi nesou X-Quota-Limit, X-Quota-Used a X-Quota-Remaining (měsíc) a RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (minuta). Po vyčerpání měsíční kvóty přijde 402 quota_exceeded, při překročení limitu za minutu 429 rate_limited s Retry-After; odmítnuté požadavky (429) se do měsíční kvóty nepočítají.
API přijímá pouze HTTPS a protokoly HTTP/1.1 a HTTP/2. Požadavek v HTTP/1.0 odmítne už vstupní brána odpovědí 426 Upgrade Required (prostý text, bez X-Request-Id). Týká se to např. nástroje ab (ApacheBench) nebo Fiddler Composeru s verzí HTTP/1.0; přepněte klienta na HTTP/1.1.
Chyby
Každá chyba je dokument podle RFC 9457 (application/problem+json) s poli type, title, status, detail, strojovým code a requestId. Každá odpověď má hlavičku X-Request-Id; uveďte ji, když píšete na podporu.
{"type":"/docs/errors#watchlist_not_found","title":"Watchlist not found","status":404,
"detail":"Watchlist 7 does not exist in this account.","code":"watchlist_not_found","requestId":"0HN…"}
Kódy: missing_api_key, invalid_api_key (401), account_disabled (403), quota_exceeded, watch_limit_exceeded (402), rate_limited (429), invalid_country, invalid_registration_number, query_required, invalid_email, name_required, unknown_event_type, webhook_url_must_be_https, no_webhook_url, unknown_delivery_status, cannot_revoke_current_key (400), company_not_found, watchlist_not_found, item_not_found, key_not_found (404). Validační chyby nesou value a allowed. Odpověď 426 Upgrade Required není problem document: vrací ji vstupní brána na požadavek v HTTP/1.0 (viz Autentizace).
Firmy
GET /api/v1/companies/{country}/{ico} country = CZ | SK; IČO bez nul na začátku funguje také
GET /api/v1/companies/search?q=&country=&limit= název (překlepy, bez diakritiky) nebo prefix IČO
Odpověď obsahuje název, DIČ, právní formu, stav, sídlo (u CZ s kódem adresního místa RÚIAN), NACE, blok vat (viz níže), příznak insolvence, přítomnost v registrech (registrations) a atribuci zdroje. Slovenské firmy mají historii názvů, adres a orgánů; české zatím jen aktuální stav a události. Českou firmu, kterou máme jen ze základního exportu ČSÚ, při prvním dotazu doplníme z ARES a z registru plátců DPH (odpověď pak trvá o něco déle, typicky do 1,5 s).
Ověření plátce DPH
GET /api/v1/companies/{country}/{ico}/vat?vies=true živá kontrola jedné firmy
POST /api/v1/vat/check {"vatNumbers":["CZ27074358","CZ699001234","SK2020273893"],"vies":false} dávka až 100 DIČ
K čemu je. Odpověď na otázku „můžu tomuto dodavateli zaplatit fakturu s DPH a odečíst si ji?“ v okamžiku, kdy na tom záleží. Vrací druh registrace (vat.status), zda jde o nespolehlivého plátce (odběratel pak ručí za jeho DPH), bankovní účty zveřejněné v registru plátců (platba na jiný účet také zakládá ručení) a volitelně ověření ve VIES. U českých firem se při každém volání ptáme ARES a registru plátců DPH Finanční správy, odpověď nese live: true a čas ověření. Slovenský registr nemá dotazovací službu; slovenské firmy obsluhujeme z denní kopie open dat Finančnej správy SR (live: false, upozornění sk_daily_copy).
Kdy ho volat. Při zaúčtování přijaté faktury a před uvolněním platby (ručení za DPH podle § 109 zákona o DPH se posuzuje k okamžiku uskutečnění plnění a platby), při zakládání nového dodavatele do kmenových dat a jednorázově dávkově přes POST /vat/check při migraci nebo pravidelné měsíční kontrole dodavatelů. Dávka je klíčovaná DIČ z faktury, takže funguje i pro skupinová DIČ (CZ699…), která nejdou převést na IČO.
Kdy ho nevolat. Při každém zobrazení stránky, seznamu nebo detailu partnera: na to je běžný lookup GET /companies/{country}/{ico}, který vrací stejný blok vat z naší databáze bez čekání na registry. Ne v cyklu nad celým portfoliem: dejte firmy do watchlistu a nechte si posílat události vat_registration_changed, vat_reliability_changed a bank_accounts_changed; sledované firmy obnovujeme z registru plátců denně. Ne pro slovenské firmy opakovaně během dne: data se mění jednou denně, lookup stačí. Volání se počítá do kvóty stejně jako lookup, trvá ale déle a zatěžuje registry třetích stran.
Stavy v vat.status. payer plátce DPH (CZ § 6 ZDPH, SK § 4, § 5, § 6): na tuzemské faktuře je DPH, odběratel má nárok na odpočet. identified_person identifikovaná osoba (CZ § 6g–6l, SK § 7 a § 7a): má DIČ jen pro přeshraniční plnění, tuzemsky fakturuje bez DPH a odběratel si DPH odečíst nesmí. ARES ji hlásí stejně jako plátce, proto samotný údaj z ARES na tuto otázku nestačí. group skupina DPH (CZ § 5a, SK § 4b): fakturuje se pod DIČ skupiny v vat.groupNumber. none není registrován. unknown zatím jsme se registru neptali. Pole vat.isPayer je true jen pro payer a group; vat.verified říká, zda stav potvrdil registr plátců, nebo je zatím odvozený jen z ARES / RPO.
Zdroje a čerstvost. CZ: ARES (zda je subjekt v registru DPH) + webová služba Finanční správy ČR „Registr plátců DPH“ (druh subjektu, nespolehlivost, účty; odstávka denně 0:00–0:10). SK: Finančná správa SR, zoznam daňových subjektov registrovaných pre DPH a zoznam platiteľov s dôvodom na zrušenie registrácie (open data, CC BY 4.0, denně). VIES: Evropská komise, validita DIČ pro intrakomunitární obchod; vies.valid je null, když je členský stát nedostupný. Historii registrace žádný z registrů strojově neposkytuje; k dispozici je stav ZANIKLY v registrations a naše události od chvíle, kdy firmu sledujeme.
Hlídání změn
GET /api/v1/watchlists {"watchlists":[…]}
POST /api/v1/watchlists {"name","webhookUrl"?,"eventTypes"?[]} → 201, webhookSecret (jen jednou)
GET /api/v1/watchlists/{id}
PATCH /api/v1/watchlists/{id} {"name"?,"webhookUrl"?,"eventTypes"?[],"isActive"?} webhookUrl "" webhook odebere
POST /api/v1/watchlists/{id}/webhook-secret nový podpisový secret, starý okamžitě přestane platit
DELETE /api/v1/watchlists/{id}
GET /api/v1/watchlists/{id}/items?after=&limit= {"items":[…],"nextCursor"}
PUT /api/v1/watchlists/{id}/items [{"country","registrationNumber","externalRef"?,"tags"?[]}] úplná synchronizace
POST /api/v1/watchlists/{id}/items přidat / upravit bez mazání
DELETE /api/v1/watchlists/{id}/items/{itemId}
DELETE /api/v1/watchlists/{id}/items/{country}/{ico}
GET /api/v1/events?after={eventId}&limit= pull feed, stejný tvar jako webhook
GET /api/v1/deliveries?status=pending|delivered|failed log doručení webhooků
Synchronizace vrací added, updated, removed, itemCount, notFound (IČO, která v registrech neznáme) a invalid. Seznamy stránkují kurzorem: opakujte dotaz s after=nextCursor, dokud nextCursor není null.
Typy událostí: entity_created , entity_dissolved , name_changed , address_changed , legal_form_changed , status_changed , statutory_body_changed , vat_registration_changed , vat_reliability_changed , bank_accounts_changed , insolvency_changed , registration_changed . Insolvenční příznak zatím jen pro CZ, statutární orgán jen pro SK. Události k DPH: vat_registration_changed (CZ i SK; payload old/new se stavem, verified a případně correction: true, když registr plátců zpřesnil stav odvozený z ARES), vat_reliability_changed (nespolehlivý plátce CZ, rizikový platiteľ SK) a bank_accounts_changed (CZ, zveřejněné účty: added/removed). ARES o změnách v registru DPH nenotifikuje, proto sledované firmy obnovujeme z registru plátců každý den; změna registrace se tak objeví do 24 hodin, ostatní změny z ARES do hodiny.
Webhook je POST s JSON tělem a hlavičkou X-ApiPoint-Signature: t=<unix>,v1=<hex>, kde v1 = HMAC-SHA256(secret, t + "." + body). Odpovězte 2xx do 15 s; jinak opakujeme po 1 min, 5 min, 30 min, 2 h, 6 h a 24 h. Události nemají garantované pořadí, deduplikujte podle id.
MCP server
URL https://apipoint.app/api/mcp (Streamable HTTP), hlavička Authorization: Bearer <klíč>. Nástroje company_lookup(country, registrationNumber), company_search(query, country?, limit?) a company_vat_check(country, registrationNumber, vies?). Volání se počítají do kvóty jako dotazy.
// Claude Code claude mcp add --transport http apipoint https://apipoint.app/api/mcp --header "Authorization: Bearer ap_live_…"
OpenAPI a interaktivní reference
Strojový popis: /api/openapi/v1.json (import do Postmanu, generování SDK přes Kiota nebo openapi-generator).
Otevřít interaktivní referenci – vložte klíč vpravo nahoře do „Authentication“ a volejte endpointy přímo z prohlížeče.