API, webhooki in MCP: poveži svoj ERP z evidenco

Če kmetijo vodiš v sistemu ERP, v preglednici stroškov ali v programu svojega svetovalca, nima smisla vnašati opravil dvakrat. To je dokumentacija, kako od zunaj dobiti evidenco, stroške in stanje izpolnjevanja obveznosti ter kako vanjo vpisovati opravila iz sistema, ki ga že uporabljaš.

Osnovni naslov je https://agrogps-api.fly.dev/api/v1. V produkciji je od 17. septembra 2026. Vedno odgovarja v JSON, tudi pri napakah.

Dva načina prijave

Ključ se ustvari enkrat iz tvoje seje in se pokaže samo enkrat: potem hranimo le njegov hash. Če ga izgubiš, ga prekličeš in ustvariš novega. Ključ samo za branje, ki poskuša pisati, dobi 403 AUT_004. Ključi ne morejo ustvarjati ali brisati drugih ključev ali webhookov: to vedno gre prek seje č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"}'

Kaj lahko bereš

S ključem za pisanje lahko opravila tudi vpisuješ z POST /sync/entries, z enakim telesom, kot ga uporablja aplikacija. Sinhronizacija gre prek since, zato nočni proces prenese samo tisto, kar se je spremenilo.

Začni brezplačno

Podpisani webhooki

Namesto da sprašuješ vsakih pet minut, te obvestimo mi. Registriramo javni naslov https in pošljemo obvestilo, ko se kaj zgodi na kmetiji, kjer si lastnik ali upravitelj.

Vsaka dostava nosi X-Agro-Event, X-Agro-Timestamp v sekundah Unix in X-Agro-Signature s HMAC-SHA256 od "<timestamp>.<cuerpo>". Preveri oboje: podpis in da ura ni odstopala za več kot pet 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"])

Pravila dostave, jasno, da te nič ne preseneti: en poskus, šest sekund čakanja in brez ponovitev. Preusmeritvam ne sledimo in zavračamo zasebne naslove, naslove lokalne povezave in metapodatkov oblaka, tako pri registraciji naslova kot pri razreševanju DNS vsake dostave. Če tvoj sistem potrebuje jamstva, uporabi webhook kot obvestilo in GET /sync/entries z since kot varnostno mrežo: obvestilo je vljudnost, resnica je API.

MCP za pomočnike umetne inteligence

Isti API je na voljo tudi kot strežnik MCP, protokol, s katerim se pomočniki povezujejo z orodji. Pomočnika lahko tako vprašaš, katere kmetije zamujajo, koliko je stala sezona ali kaj je treba izpolniti pred nadzorom.

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

Razpoložljiva orodja: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending in record_entry. Zadnje deluje samo s ključem za pisanje, v zgodovini je označeno kot zapis prek API in nikoli ničesar ne pošlje upravi.

Zakaj API ni za goljufanje

API nad evidenco s pravno veljavo mora prenesti pogled od blizu. V Španiji RD 1054/2022 dovoljuje vodenje evidence s katerim koli informacijskim sistemom, ki izpolnjuje zahteve priloge II in je povezljiv s sistemom SIEX, ter jasno določa, da je za resničnost odgovoren nosilec, ne program. To velja povsod: naš del je celovitost, zapisana v kodi.

Napake

Vedno {"code":"INT_NNN","message":"…"}, nikoli sled sklada. Najpogosteje boš videl: AUT_003 neveljaven ključ, AUT_004 ključ samo za branje, AUT_429 preveč poskusov, AUT_503 prijava ni na voljo (to ni isto kot napačen ključ: poskusi znova), INT_003 naslov, ki ni https, INT_403 operacija, ki zahteva sejo, INT_404 ključ ali webhook, ki ni tvoj.

Kako dobiš ključ

API je del paketov za podjetja in svetovalce. Če že imaš račun, ključ ustvariš kar v aplikaciji. Če povezavo presojaš pred nakupom, piši na support@agrogps.eu, kateri sistem želiš povezati, in dobiš preizkusni dostop. Dokumentacija je javna in brezplačna: raje vidimo, da jo pogledaš, preden plačaš.

Začni brezplačno

Pogosta vprašanja

Lahko vodim celotno evidenco iz ERP brez odpiranja aplikacije? Da, za vpisovanje in branje. Ne za uradno oddajo upravi, ki obstaja samo v Španiji in zahteva sejo človeka z dovoljenjem za oddajo. To je premišljena odločitev: to dejanje ima pravne posledice in ga ne sme sprožiti samodejni proces. V Sloveniji se centralna evidenca vnaša ročno, zato je Agro GPS ne more oddati namesto tebe.

So podatki moji? Da. Celoten izvoz je vedno brezplačen, tudi če prekineš naročnino, in prek API dobiš natanko to, kar vidiš na zaslonu, skupaj z zgodovino in sledjo sprememb.

Ali je število klicev omejeno? Za običajno uporabo ERP ni objavljene kvote. Preizkus webhooka je omejen na dvajsetkrat na uporabnika in IP vsakih deset minut, da funkcije nihče ne uporablja kot vir prometa.

Kaj, če API spremenite? Različica je v naslovu. Dokler je v1 objavljena, polj ne odstranjujemo in ne spreminjamo pomena obstoječih; novo se dodaja. Če bi kdaj nastala v2, bi delovali vzporedno.

Je strežnik MCP v npm? Še ne. Danes se zaganja iz repozitorija; o objavi še ni odločeno. Zgornja nastavitev bo delovala na dan objave.

Je to primerno za svetovalca z veliko strankami? Za to je advisor/portfolio: en klic ti pove, katere kmetije imajo evidenco urejeno in katere imajo nepopolna opravila, brez odpiranja ene za drugo.