API, webhooky a MCP: prepoj svoj ERP s evidenciou
Ak vedieš podnik v ERP, v tabuľke nákladov alebo v programe svojho poradcu, nemá zmysel ťukať zásahy dvakrát. Toto je dokumentácia, ako zvonku vytiahnuť evidenciu, náklady a stav plnenia povinností a ako do nej zapisovať zásahy zo systému, ktorý už používaš.
Základná adresa je https://agrogps-api.fly.dev/api/v1. V prevádzke je od 17. septembra 2026. Vždy odpovedá v JSON, aj pri chybách.
Dva spôsoby overenia
| Kto volá | Hlavička | Čo môže robiť |
|---|---|---|
| Aplikácia alebo web | Authorization: Bearer <sesión> | Všetko, vrátane vytvárania a rušenia kľúčov |
| Externý systém | X-API-Key: agk_… | Čítať, alebo čítať aj zapisovať podľa rozsahu kľúča |
Kľúč sa vytvára raz z tvojej relácie a zobrazí sa iba raz: potom uchovávame len jeho hash. Ak ho stratíš, zruší sa a vytvorí sa nový. Kľúč len na čítanie, ktorý sa pokúsi zapisovať, dostane 403 AUT_004. Kľúče nemôžu vytvárať ani mazať iné kľúče či webhooky: to vždy ide cez reláciu človeka.
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"}'Čo môžeš čítať
| Endpoint | Vracia |
|---|---|
GET /farms | Podniky držiteľa kľúča a jeho rolu |
GET /sync/entries?farm_id=…&since=0 | Všetky zásahy so všetkými poľami, stránkované cez next |
GET /groups/:id/overview | Prehľad skupiny: zásahy, náklady, príjmy, marža, ošetrené hektáre a plodina podľa podniku |
GET /advisor/portfolio | Portfólio poradcu: ktoré podniky majú evidenciu v poriadku a ktoré nie |
GET /advisor/farms/:id/pending | Polia, ktoré treba doplniť, zásah po zásahu |
GET /notebook/entries/:id/history | Kto čo a kedy zmenil v zásahu |
S kľúčom na zápis môžeš navyše zapisovať zásahy cez POST /sync/entries, s rovnakým telom, aké používa aplikácia. Synchronizácia ide cez since, takže nočný proces si stiahne len to, čo sa zmenilo.
Podpísané webhooky
Namiesto otázky každých päť minút ťa upozorníme sami. Zaregistrujeme verejnú adresu https a pošleme upozornenie, keď sa niečo stane v podniku, kde si vlastník alebo správca.
| Udalosť | Kedy sa spustí |
|---|---|
entry.pushed | Synchronizujú sa zásahy a aspoň jeden sa prijme |
entry.reviewed | Poradca alebo vlastník schváli alebo označí zásah |
webhook.test | Stlačíš test |
Každé doručenie nesie X-Agro-Event, X-Agro-Timestamp v sekundách Unix a X-Agro-Signature s HMAC-SHA256 z "<timestamp>.<cuerpo>". Over obe veci: podpis a to, že hodiny sa neodchýlili o viac ako päť minút.
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"])Pravidlá doručovania, jasne, aby ťa nič neprekvapilo: jeden pokus, šesť sekúnd čakania a bez opakovania. Nesledujeme presmerovania a odmietame súkromné adresy, adresy lokálneho spojenia a metadát cloudu, pri registrácii adresy aj pri preklade DNS každého doručenia. Ak tvoj systém potrebuje záruky, použi webhook ako upozornenie a GET /sync/entries so since ako záchrannú sieť: upozornenie je zdvorilosť, pravdou je API.
MCP pre asistentov umelej inteligencie
To isté API je dostupné aj ako MCP server, protokol, ktorým sa asistenti pripájajú k nástrojom. Asistenta sa tak môžeš pýtať, ktoré podniky meškajú, koľko stála sezóna alebo čo treba doplniť pred 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 iba s kľúčom na zápis, v histórii sa označí ako zápis cez API a nikdy nič neposiela úradom.
Prečo sa API nedá zneužiť na podvádzanie
API nad záznamom s právnou váhou musí zniesť pohľad zblízka. V Španielsku RD 1054/2022 dovoľuje viesť záznamy v akomkoľvek informačnom systéme, ktorý spĺňa požiadavky prílohy II a je interoperabilný so systémom SIEX, a jasne hovorí, že za pravdivosť zodpovedá držiteľ, nie program. Platí to všade: našou časťou je integrita a je zapísaná v kóde.
| Čo by sa niekto mohol pokúsiť urobiť | Čo urobí API |
|---|---|
| Zapísať dnes s dátumom spred mesiacov | Každý zásah uchováva deklarovaný dátum aj skutočný príchod na server a história zaznamená dni oneskorenia |
| Zapísať s budúcim dátumom | Odmietne sa, ak presahuje 24 hodín od teraz |
| Zapisovať bez človeka za tým | Každý zásah má autora a tie, ktoré prídu cez kľúč, sú označené prefixom daného kľúča |
| Zmazať, čo prekáža | Nič sa nemaže: zmazania sú náhrobky s dátumom |
| Automaticky odoslať úradom | Úradné odoslanie (existuje iba v Španielsku) vyžaduje reláciu oprávneného človeka: kľúč dostane 403 SIE_403 |
Chyby
Vždy {"code":"INT_NNN","message":"…"}, nikdy výpis zásobníka. Najčastejšie uvidíš: AUT_003 neplatný kľúč, AUT_004 kľúč len na čítanie, AUT_429 priveľa pokusov, AUT_503 overenie nie je dostupné (to nie je to isté ako zlý kľúč: skús znova), INT_003 adresa, ktorá nie je https, INT_403 operácia vyžadujúca reláciu, INT_404 kľúč alebo webhook, ktorý nie je tvoj.
Ako získať kľúč
API je súčasťou plánov pre firmy a poradcov. Ak už máš účet, kľúč vytvoríš priamo v aplikácii. Ak prepojenie zvažuješ ešte pred nákupom, napíš na support@agrogps.eu, aký systém chceš prepojiť, a dáme ti skúšobný prístup. Dokumentácia je verejná a bezplatná: radšej, keď si ju pozrieš pred platbou.
Časté otázky
Môžem viesť celú evidenciu z ERP bez otvorenia aplikácie? Áno na zápis a čítanie. Nie na úradné odoslanie, ktoré existuje iba v Španielsku a vyžaduje reláciu človeka s oprávnením odosielať. Je to zámerné rozhodnutie: tento úkon má právne následky a nemá ho spúšťať automatický proces.
Sú dáta moje? Áno. Úplný export je vždy zadarmo, aj keď zrušíš predplatné, a cez API si odnesieš presne to, čo vidíš na obrazovke, vrátane histórie a stopy zmien.
Je obmedzený počet volaní? Pre bežné používanie ERP nie je zverejnená kvóta. Test webhooku je obmedzený na dvadsaťkrát na používateľa a IP každých desať minút, aby funkciu nikto nepoužíval ako zdroj prevádzky.
Čo ak API zmeníte? Verzia je v adrese. Kým bude v1 zverejnená, neodstraňujeme polia ani nemeníme význam existujúcich; nové sa pridáva. Ak by raz vznikla v2, fungovali by vedľa seba.
Je MCP server v npm? Zatiaľ nie. Dnes sa spúšťa z repozitára; o zverejnení sa ešte nerozhodlo. Konfigurácia vyššie je tá, ktorá bude fungovať v deň zverejnenia.
Hodí sa to pre poradcu s mnohými klientmi? Na to je advisor/portfolio: jedno volanie ti povie, ktoré podniky majú evidenciu v poriadku a ktoré majú neúplné zásahy, bez otvárania jedného po druhom.