API, webhookok és MCP: kösd össze a rendszeredet a naplóval

Ha a gazdaságot vállalatirányítási rendszerben, költségtáblázatban vagy a tanácsadód programjában viszed, nincs értelme kétszer begépelni a műveleteket. Ez a dokumentáció arról szól, hogyan hozd ki kívülről a naplót, a költségeket és a megfelelés állapotát, és hogyan rögzíts műveleteket abból a rendszerből, amit már használsz.

Az alapcím https://agrogps-api.fly.dev/api/v1. 2026. szeptember 17. óta éles. Mindig JSON-ban válaszol, hiba esetén is.

Kétféle azonosítás

A kulcsot egyszer hozod létre a munkamenetedből, és csak egyszer jelenik meg: utána csak a hash-ét tároljuk. Ha elveszted, visszavonod és újat hozol létre. Egy csak olvasható kulcs, amely írni próbál, 403 AUT_004 választ kap. Kulcsok nem hozhatnak létre és nem törölhetnek más kulcsokat vagy webhookokat: ehhez mindig egy ember munkamenete kell.

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"}'

Mit olvashatsz

Írási kulccsal műveleteket is rögzíthetsz a POST /sync/entries hívással, ugyanazzal a tartalommal, amit az app használ. A szinkronizálás a since szerint megy, így egy éjszakai futás csak azt hozza le, ami változott.

Kezdd el ingyen

Aláírt webhookok

Ahelyett, hogy ötpercenként kérdeznél, mi szólunk. Megadsz egy nyilvános https címet, és értesítést küldünk, amikor történik valami egy olyan gazdaságban, ahol tulajdonos vagy felelős vagy.

Minden kézbesítés tartalmazza a X-Agro-Event, a X-Agro-Timestamp (Unix-másodperc) és a X-Agro-Signature fejlécet, utóbbi a "<timestamp>.<cuerpo>" HMAC-SHA256 értéke. Ellenőrizd mindkettőt: az aláírást, és hogy az óra nem tér-e el öt percnél többel.

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"])

A kézbesítés szabályai, világosan, hogy ne érjen meglepetés: egy próbálkozás, hat másodperc várakozás és nincs újrapróbálás. Nem követjük az átirányításokat, és elutasítjuk a privát, a link-local és a felhős metaadat-címeket, a cím megadásakor és minden kézbesítés DNS-feloldásakor is. Ha a rendszerednek garanciák kellenek, használd a webhookot jelzésként, a GET /sync/entries hívást pedig since értékkel biztonsági hálóként: az értesítés udvariasság, az API az igazság.

MCP AI-asszisztenseknek

Ugyanez az API MCP-szerverként is elérhető, ezzel a protokollal kapcsolódnak az asszisztensek eszközökhöz. Megkérdezheted például egy asszisztenstől, mely gazdaságok vannak lemaradásban, mennyibe került az idény, vagy mi hiányzik egy ellenőrzés előtt.

{ "mcpServers": { "agro-gps": {
  "command": "npx", "args": ["-y", "agro-gps-mcp"],
  "env": { "AGROGPS_API_KEY": "agk_…" } } } }

Elérhető eszközök: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending és record_entry. Az utolsó csak írási kulccsal működik, a naplóban API-n keresztüli írásként jelenik meg, és soha nem küld semmit a hatóságoknak.

Miért nem lehet az API-val csalni

Egy jogi súlyú nyilvántartásra épülő API-nak ki kell bírnia a közelebbi vizsgálatot. Spanyolországban az RD 1054/2022 megengedi, hogy a naplót bármilyen informatikai rendszerben vezessék, amely megfelel a II. melléklet követelményeinek és adatot cserél a SIEX-szel, és egyértelművé teszi, hogy az adatok valódiságáért a gazdálkodó felel, nem a program. A mi részünk az adatok sértetlensége, és ez minden országban a kódba van építve.

Hivatalos beküldés ma csak Spanyolországban létezik, és ott régiónként jóváhagyásra vár. A Nébih eGN-rendszerébe az Agro GPS ma nem küld adatot, azt továbbra is neked kell bevinned: az API-n keresztül a naplót olvasod és írod.

Hibák

Mindig {"code":"INT_NNN","message":"…"}, soha nem veremkiírás. A leggyakoribbak: AUT_003 érvénytelen kulcs, AUT_004 csak olvasható kulcs, AUT_429 túl sok próbálkozás, AUT_503 a hitelesítés nem érhető el (nem ugyanaz, mint a rossz kulcs: próbáld újra), INT_003 nem https cím, INT_403 munkamenetet igénylő művelet, INT_404 nem a tiéd a kulcs vagy a webhook.

Hogyan kapsz kulcsot

Az API a vállalati és tanácsadói csomagok része. Ha már van fiókod, a kulcsot magában az appban hozod létre. Ha vásárlás előtt mérlegeled az integrációt, írj a support@agrogps.eu címre, hogy milyen rendszert kötnél be, és adunk teszthozzáférést. A dokumentáció nyilvános és ingyenes: inkább nézd meg, mielőtt fizetsz.

Kezdd el ingyen

Gyakori kérdések

Vezethetem az egész naplót a rendszeremből az app megnyitása nélkül? Rögzítésre és olvasásra igen. A hatósághoz való hivatalos beküldésre nem, mert ahhoz beküldési jogosultsággal rendelkező személy munkamenete kell. Ez tudatos döntés: ennek a lépésnek jogi következményei vannak, és nem indíthatja el automatikus folyamat.

Az adatok az enyémek? Igen. A teljes export mindig ingyenes, lemondás után is, és az API-n keresztül pontosan ugyanazt viszed magaddal, amit a képernyőn látsz, az előzményekkel és a változásnaplóval együtt.

Van hívási korlát? Egy vállalatirányítási rendszer szokásos használatára nincs közzétett kvóta. A webhook tesztelése felhasználónként és IP-címenként tíz percen belül húsz alkalomra korlátozott, hogy senki ne használja forgalom generálására.

Mi van, ha megváltoztatjátok az API-t? A verzió a címben van. Amíg a v1 közzé van téve, nem veszünk el mezőket és nem változtatjuk meg a meglévők jelentését; az újat hozzáadjuk. Ha egyszer lesz v2, a kettő párhuzamosan él.

Fent van az MCP-szerver az npm-en? Még nincs. Ma a tárolóból fut; a közzétételről még nincs döntés. A fenti beállítás az, amelyik a közzététel napján működni fog.

Jó ez egy sok ügyféllel dolgozó tanácsadónak? Erre való az advisor/portfolio: egy hívás megmondja, mely gazdaságok naprakészek és melyekben vannak hiányos műveletek, anélkül, hogy egyenként megnyitnád őket.