API, webhookovi i MCP: poveži svoj ERP s evidencijom
Ako gospodarstvo vodiš u ERP-u, tablici troškova ili programu svog savjetnika, nema smisla dvaput upisivati zahvate. Ovo je dokumentacija kako izvana izvući evidenciju, troškove i stanje ispunjavanja obveza te kako u nju upisivati zahvate iz sustava koji već koristiš.
Osnovna adresa je https://agrogps-api.fly.dev/api/v1. U produkciji je od 17. rujna 2026. Uvijek odgovara u JSON-u, i kod pogrešaka.
Dva načina prijave
| Tko poziva | Zaglavlje | Što može |
|---|---|---|
| Aplikacija ili web | Authorization: Bearer <sesión> | Sve, uključujući stvaranje i opoziv ključeva |
| Vanjski sustav | X-API-Key: agk_… | Čitanje, ili čitanje i pisanje prema opsegu ključa |
Ključ se stvara jednom iz tvoje sesije i prikazuje se samo jednom: nakon toga čuvamo samo njegov hash. Ako ga izgubiš, opozove se i stvori novi. Ključ samo za čitanje koji pokuša pisati dobiva 403 AUT_004. Ključevi ne mogu stvarati ni brisati druge ključeve ni webhookove: to uvijek ide kroz sesiju osobe.
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"}'Što možeš čitati
| Endpoint | Vraća |
|---|---|
GET /farms | Gospodarstva vlasnika ključa i njegovu ulogu |
GET /sync/entries?farm_id=…&since=0 | Sve zahvate sa svim poljima, po stranicama preko next |
GET /groups/:id/overview | Pregled grupe: zahvati, trošak, prihodi, marža, tretirani hektari i kultura po gospodarstvu |
GET /advisor/portfolio | Portfelj savjetnika: koja gospodarstva imaju urednu evidenciju, a koja ne |
GET /advisor/farms/:id/pending | Polja koja nedostaju, zahvat po zahvat |
GET /notebook/entries/:id/history | Tko je što i kada promijenio u zahvatu |
Ključem za pisanje možeš i upisivati zahvate preko POST /sync/entries, s istim tijelom koje koristi aplikacija. Sinkronizacija ide preko since, pa noćni proces preuzima samo ono što se promijenilo.
Potpisani webhookovi
Umjesto da pitaš svakih pet minuta, mi te obavijestimo. Registriramo javnu https adresu i šaljemo obavijest kad se nešto dogodi na gospodarstvu na kojem si vlasnik ili upravitelj.
| Događaj | Kada se okida |
|---|---|
entry.pushed | Zahvati se sinkroniziraju i barem jedan je prihvaćen |
entry.reviewed | Savjetnik ili nositelj odobri ili označi zahvat |
webhook.test | Pritisneš test |
Svaka isporuka nosi X-Agro-Event, X-Agro-Timestamp u Unix sekundama i X-Agro-Signature s HMAC-SHA256 od "<timestamp>.<cuerpo>". Provjeri oboje: potpis i da sat nije odstupio više od pet minuta.
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"])Pravila isporuke, jasno da te ništa ne iznenadi: jedan pokušaj, šest sekundi čekanja i bez ponavljanja. Ne slijedimo preusmjeravanja i odbijamo privatne adrese, adrese lokalne veze i metapodataka oblaka, i pri registraciji adrese i pri razrješavanju DNS-a svake isporuke. Ako tvoj sustav treba jamstva, koristi webhook kao obavijest, a GET /sync/entries sa since kao sigurnosnu mrežu: obavijest je ljubaznost, istina je API.
MCP za AI asistente
Isti API dostupan je i kao MCP poslužitelj, protokol kojim se asistenti spajaju na alate. Asistenta tako možeš pitati koja gospodarstva kasne, koliko je koštala sezona ili što treba ispuniti prije inspekcije.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Dostupni alati: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending i record_entry. Posljednji radi samo s ključem za pisanje, u povijesti je označen kao upis preko API-ja i nikada ništa ne šalje upravi.
Zašto API nije za varanje
API nad evidencijom s pravnom vrijednošću mora izdržati pogled izbliza. U Španjolskoj RD 1054/2022 dopušta vođenje evidencije u bilo kojem informatičkom sustavu koji ispunjava zahtjeve priloga II i povezuje se sa sustavom SIEX, i jasno kaže da je za istinitost odgovoran nositelj, a ne program. To vrijedi svugdje: naš dio je cjelovitost, zapisana u kodu.
| Što bi netko mogao pokušati | Što radi API |
|---|---|
| Danas upisati s datumom od prije nekoliko mjeseci | Svaki zahvat čuva navedeni datum i stvarni dolazak na poslužitelj, a povijest bilježi dane kašnjenja |
| Upisati s budućim datumom | Odbija se ako je više od 24 sata od sada |
| Pisati bez osobe iza toga | Svaki zahvat ima autora, a oni koji stignu ključem označeni su prefiksom tog ključa |
| Obrisati ono što smeta | Ništa se ne briše: brisanja su nadgrobni zapisi s datumom |
| Automatski poslati upravi | Službena predaja (postoji samo u Španjolskoj) traži sesiju ovlaštene osobe: ključ dobiva 403 SIE_403 |
Pogreške
Uvijek {"code":"INT_NNN","message":"…"}, nikad trag stoga. Najčešće ćeš vidjeti: AUT_003 nevažeći ključ, AUT_004 ključ samo za čitanje, AUT_429 previše pokušaja, AUT_503 prijava nije dostupna (to nije isto što i pogrešan ključ: pokušaj ponovno), INT_003 adresa koja nije https, INT_403 radnja koja traži sesiju, INT_404 ključ ili webhook koji nije tvoj.
Kako dobiti ključ
API dolazi uz pakete za tvrtke i savjetnike. Ako već imaš račun, ključ stvaraš u samoj aplikaciji. Ako povezivanje procjenjuješ prije kupnje, piši na support@agrogps.eu koji sustav želiš povezati i dobit ćeš probni pristup. Dokumentacija je javna i besplatna: radije da je pogledaš prije plaćanja.
Česta pitanja
Mogu li cijelu evidenciju voditi iz ERP-a bez otvaranja aplikacije? Da, za upis i čitanje. Ne za službenu predaju upravi, koja postoji samo u Španjolskoj i traži sesiju osobe s ovlaštenjem za predaju. To je namjerna odluka: taj čin ima pravne posljedice i ne smije ga pokrenuti automatski proces. U Hrvatskoj FIS ne prima podatke iz komercijalnih programa, pa tamo ionako nema što predati.
Jesu li podaci moji? Da. Potpuni izvoz uvijek je besplatan, i ako otkažeš pretplatu, a preko API-ja dobivaš točno ono što vidiš na zaslonu, uključujući povijest i trag promjena.
Je li broj poziva ograničen? Za uobičajenu uporabu ERP-a nema objavljene kvote. Test webhooka ograničen je na dvadeset puta po korisniku i IP-u svakih deset minuta, da nitko funkciju ne koristi kao izvor prometa.
Što ako promijenite API? Verzija je u adresi. Dok je v1 objavljena, ne uklanjamo polja niti mijenjamo značenje postojećih; novo se dodaje. Ako jednom bude v2, radile bi usporedno.
Je li MCP poslužitelj na npm-u? Još nije. Danas se pokreće iz repozitorija; o objavi još nije odlučeno. Gornja postavka radit će na dan objave.
Je li to za savjetnika s puno klijenata? Za to služi advisor/portfolio: jedan poziv kaže ti koja gospodarstva imaju urednu evidenciju, a koja nepotpune zahvate, bez otvaranja jednog po jednog.