API, webhooky a MCP: propoj svůj ERP s evidencí
Pokud vedeš podnik v ERP, v tabulce nákladů nebo v programu svého poradce, nemá smysl zapisovat zásahy dvakrát. Tady je dokumentace, jak z evidence zvenku vytáhnout zásahy, náklady a stav plnění povinností a jak zásahy zapisovat ze systému, který už používáš.
Základní adresa je https://agrogps-api.fly.dev/api/v1. V provozu je od 17. září 2026. Vždy odpovídá v JSON, i při chybách.
Dva způsoby, jak se identifikovat
| Kdo volá | Hlavička | Co může |
|---|---|---|
| Aplikace nebo web | Authorization: Bearer <sesión> | Všechno, včetně vytváření a rušení klíčů |
| Externí systém | X-API-Key: agk_… | Číst, nebo číst i zapisovat podle rozsahu klíče |
Klíč se vytvoří jednou z tvé relace a ukáže se jen jednou: pak ukládáme jen jeho hash. Když ho ztratíš, zrušíš ho a vytvoříš nový. Klíč jen pro čtení, který se pokusí zapisovat, dostane 403 AUT_004. Klíče nemůžou vytvářet ani mazat jiné klíče ani webhooky: to vždy vyžaduje relaci člověka.
curl -X POST https://agrogps-api.fly.dev/api/v1/api-keys \
-H "Authorization: Bearer $SESION" \
-H "Content-Type: application/json" \
-d '{"name":"ERP Sage","scope":"read"}'Co můžeš číst
| Endpoint | Vrací |
|---|---|
GET /farms | Podniky držitele klíče, s jeho rolí |
GET /sync/entries?farm_id=…&since=0 | Všechny zásahy se všemi poli evidence, stránkované přes next |
GET /groups/:id/overview | Přehled skupiny: zásahy, náklady, příjmy, marže, ošetřené hektary a plodina v každém podniku |
GET /advisor/portfolio | Portfolio poradce: které podniky jsou v pořádku a které ne |
GET /advisor/farms/:id/pending | Pole, která zbývá vyplnit, zásah po zásahu |
GET /notebook/entries/:id/history | Kdo co a kdy v zásahu změnil |
S klíčem pro zápis můžeš také zapisovat zásahy přes POST /sync/entries, se stejným tělem, jaké používá aplikace. Synchronizace jde přes since, takže noční běh si stáhne jen to, co se změnilo.
Podepsané webhooky
Místo abys se ptal každých pět minut, dáme ti vědět my. Zaregistruješ veřejnou adresu https a my pošleme upozornění, když se něco stane v podniku, kde jsi vlastník nebo správce.
| Událost | Kdy se spustí |
|---|---|
entry.pushed | Synchronizují se zásahy a aspoň jeden je přijat |
entry.reviewed | Poradce nebo vlastník schválí nebo označí zásah |
webhook.test | Stiskneš test |
Každé doručení nese X-Agro-Event, X-Agro-Timestamp v unixových sekundách a X-Agro-Signature s HMAC-SHA256 z "<timestamp>.<cuerpo>". Ověř obojí: podpis a to, že se hodiny neliší o víc než pět minut.
import hmac, hashlib, time
ts = request.headers["X-Agro-Timestamp"]
assert abs(time.time() - int(ts)) < 300
esperada = "sha256=" + hmac.new(
secreto.encode(), ts.encode() + b"." + cuerpo, hashlib.sha256
).hexdigest()
ok = hmac.compare_digest(esperada, request.headers["X-Agro-Signature"])Pravidla doručování, řečená jasně, ať tě nic nepřekvapí: jeden pokus, šest sekund čekání a žádné opakování. Nesledujeme přesměrování a odmítáme soukromé adresy, adresy link-local a adresy metadat cloudu, jak při registraci adresy, tak při překladu DNS u každého doručení. Pokud tvůj systém potřebuje záruky, ber webhook jako upozornění a GET /sync/entries se since jako záchrannou síť: upozornění je zdvořilost, API je pravda.
MCP pro AI asistenty
Stejné API je dostupné jako server MCP, protokol, kterým se asistenti připojují k nástrojům. Můžeš se asistenta zeptat třeba na to, které podniky mají zpoždění, kolik stála sezóna nebo co chybí před kontrolou.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Dostupné nástroje: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending a record_entry. Poslední funguje jen s klíčem pro zápis, v historii se označí jako zápis přes API a nikdy nic neposílá úřadům.
Proč se přes API nedá podvádět
API nad evidencí s právní váhou musí snést pohled zblízka. Ve Španělsku RD 1054/2022 dovoluje vést evidenci v jakémkoli informačním systému, který splňuje požadavky přílohy II a umí si vyměňovat data se SIEX, a jasně říká, že za pravdivost odpovídá podnikatel, ne program. Naše část je integrita dat a je zabudovaná v kódu, v každé zemi.
| Co by se někdo mohl pokusit | Co udělá API |
|---|---|
| Zapsat dnes zásah s datem před několika měsíci | Každý zásah ukládá uvedené datum i skutečný čas příchodu na server a historie zaznamená počet dní zpoždění |
| Zapsat zásah s budoucím datem | Odmítne se, pokud je o víc než 24 hodin v budoucnosti |
| Zapisovat bez člověka za tím | Každý zásah má autora a ty, které přijdou klíčem, jsou označené předponou toho klíče |
| Smazat, co překáží | Nic se nemaže: smazání jsou náhrobky s datem |
| Automaticky odesílat úřadům | Oficiální odeslání vyžaduje relaci oprávněné osoby: klíč dostane 403 SIE_403 |
Oficiální odesílání dnes existuje jen ve Španělsku a čeká tam na schválení region po regionu. Do českého Portálu farmáře Agro GPS nic neodesílá: přes API evidenci čteš a zapisuješ.
Chyby
Vždy {"code":"INT_NNN","message":"…"}, nikdy výpis zásobníku. Nejčastější: AUT_003 neplatný klíč, AUT_004 klíč jen pro čtení, AUT_429 příliš mnoho pokusů, AUT_503 ověření nedostupné (to není totéž co špatný klíč: zkus to znovu), INT_003 adresa, která není https, INT_403 operace vyžadující relaci, INT_404 klíč nebo webhook, který není tvůj.
Jak získat klíč
API je součástí plánů pro firmy a poradce. Pokud už máš účet, klíč vytvoříš přímo v aplikaci. Pokud integraci zvažuješ před nákupem, napiš na support@agrogps.eu, jaký systém chceš připojit, a dáme ti zkušební přístup. Dokumentace je veřejná a zdarma: radši ať si ji projdeš, než zaplatíš.
Časté otázky
Můžu vést celou evidenci z ERP bez otevření aplikace? Ano pro zapisování a čtení. Ne pro oficiální odeslání úřadům, které vyžaduje relaci osoby s oprávněním odesílat. Je to záměrné rozhodnutí: ten úkon má právní důsledky a nemá ho spouštět automatický proces.
Jsou data moje? Ano. Úplný export je vždy zdarma, i když zrušíš účet, a přes API si odneseš přesně totéž, co vidíš na obrazovce, včetně historie a stopy změn.
Je nějaký limit volání? Pro běžné použití z ERP není zveřejněná kvóta. Test webhooku je omezen na dvacet pokusů na uživatele a IP za deset minut, aby tu funkci nikdo nepoužíval k posílání provozu.
Co když API změníte? Verze je v adrese. Dokud je v1 zveřejněná, neodebíráme pole ani neměníme význam existujících; nové věci přidáváme. Kdyby jednou přišla v2, budou fungovat vedle sebe.
Je MCP server v npm? Zatím ne. Dnes se spouští z repozitáře; o zveřejnění se ještě nerozhodlo. Konfigurace výše je ta, která bude fungovat v den zveřejnění.
Hodí se to poradci s mnoha klienty? Na to je advisor/portfolio: jedno volání ti řekne, které podniky jsou v pořádku a které mají nekompletní zásahy, aniž bys musel otevírat jeden po druhém.