API, tinklo kabliukai ir MCP: sujunkite ERP su žurnalu
Jei ūkį tvarkote ERP sistemoje, išlaidų lentelėje ar konsultanto programoje, nėra prasmės darbus įvesti du kartus. Tai dokumentacija, kaip iš išorės gauti žurnalą, išlaidas ir atitikties būseną bei įvesti darbus iš sistemos, kurią jau naudojate.
Pagrindas yra https://agrogps-api.fly.dev/api/v1. Veikia nuo 2026 m. rugsėjo 17 d. Visada atsako JSON formatu, net ir klaidų atveju.
Du būdai prisistatyti
| Kas kviečia | Antraštė | Ką gali daryti |
|---|---|---|
| Programėlė ar svetainė | Authorization: Bearer <sesión> | Viską, įskaitant raktų kūrimą ir atšaukimą |
| Išorinė sistema | X-API-Key: agk_… | Skaityti arba skaityti ir rašyti, priklausomai nuo rakto apimties |
Raktas sukuriamas vieną kartą iš jūsų sesijos ir parodomas tik vieną kartą: vėliau saugome tik jo maišos reikšmę. Jei jį pamestumėte, jis atšaukiamas ir sukuriamas naujas. Tik skaitymo raktas, bandantis rašyti, gauna 403 AUT_004. Raktai negali kurti ar trinti kitų raktų ar tinklo kabliukų: tai visada daroma su žmogaus sesija.
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"}'Ką galite skaityti
| Galinis taškas | Grąžina |
|---|---|
GET /farms | Rakto savininko ūkius su jo vaidmeniu |
GET /sync/entries?farm_id=…&since=0 | Visus darbus su visais laukais, suskirstytus puslapiais per next |
GET /groups/:id/overview | Grupės apžvalga: darbai, išlaidos, pajamos, marža, apdoroti hektarai ir kultūra pagal ūkį |
GET /advisor/portfolio | Konsultanto portfelis: kurie ūkiai tvarkingi, o kurie ne |
GET /advisor/farms/:id/pending | Neužpildyti laukai, darbas po darbo |
GET /notebook/entries/:id/history | Kas, ką ir kada pakeitė darbe |
Su rašymo raktu taip pat galite registruoti darbus per POST /sync/entries, su tuo pačiu užklausos turiniu, kurį naudoja programėlė. Sinchronizacija vyksta pagal since, todėl naktinis procesas parsisiunčia tik tai, kas pasikeitė.
Pasirašyti tinklo kabliukai
Užuot klausę kas penkias minutes, pranešame mes. Užregistruojate viešą https URL, ir siunčiame pranešimą, kai kas nors įvyksta ūkyje, kuriame esate savininkas ar valdytojas.
| Įvykis | Kada suveikia |
|---|---|
entry.pushed | Darbai sinchronizuojami ir bent vienas priimamas |
entry.reviewed | Konsultantas ar savininkas patvirtina ar pažymi darbą |
webhook.test | Paspaudžiate „išbandyti“ |
Kiekviename pristatyme yra X-Agro-Event, X-Agro-Timestamp Unix sekundėmis ir X-Agro-Signature su HMAC-SHA256 iš "<timestamp>.<cuerpo>". Patikrinkite abu dalykus: parašą ir tai, kad laikrodis nenukrypo daugiau nei penkias minutes.
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"])Pristatymo taisyklės, pasakytos aiškiai, kad nebūtų staigmenų: vienas bandymas, šešios sekundės laukimo ir jokių pakartojimų. Nesekame peradresavimų ir atmetame privačius, vietinio ryšio ir debesijos metaduomenų adresus tiek registruojant URL, tiek nustatant DNS kiekvienam pristatymui. Jei jūsų sistemai reikia garantijų, naudokite tinklo kabliuką kaip pranešimą, o GET /sync/entries su since kaip apsaugos tinklą: pranešimas yra mandagumas, API yra tiesa.
MCP DI asistentams
Ta pati API pasiekiama kaip MCP serveris, protokolas, kuriuo asistentai jungiasi prie įrankių. Juo galite paklausti asistento, pavyzdžiui, kurie ūkiai vėluoja, kiek kainavo sezonas ar ką dar reikia užpildyti prieš patikrinimą.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Galimi įrankiai: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending ir record_entry. Paskutinis veikia tik su rašymo raktu, istorijoje pažymimas kaip įrašas per API ir niekada nieko nesiunčia institucijoms.
Kodėl API netinka sukčiauti
Teisinę reikšmę turinčio registro API turi atlaikyti atvirą žvilgsnį. Ispanijoje RD 1054/2022 leidžia žurnalą vesti bet kokia informacine sistema, atitinkančia II priedo reikalavimus ir suderinama su SIEX, ir aiškiai nurodo, kad už duomenų teisingumą atsako savininkas, o ne programa. Mūsų dalis yra vientisumas, ir jis įdiegtas kode, visose šalyse.
| Ką kas nors galėtų bandyti | Ką daro API |
|---|---|
| Šiandien įrašyti su prieš kelis mėnesius buvusia data | Kiekvienas darbas saugo deklaruotą datą ir tikrąjį pasiekimo serveryje laiką, o istorija pažymi vėlavimo dienas |
| Įrašyti su būsima data | Atmetama, jei ji viršija 24 valandas nuo dabar |
| Rašyti be žmogaus už to | Kiekvienas darbas turi autorių, o per raktą įvesti pažymimi to rakto priešdėliu |
| Ištrinti tai, kas trukdo | Niekas netrinama: ištrynimai yra antkapiai su data |
| Automatiškai siųsti institucijoms | Oficialus siuntimas yra tik Ispanijoje (regioninis patvirtinimas dar vyksta) ir reikalauja žmogaus sesijos su leidimu: raktas gauna 403 SIE_403. Lietuvoje Agro GPS niekur nesiunčia |
Klaidos
Visada {"code":"INT_NNN","message":"…"}, niekada klaidų sekos. Dažniausiai matysite: AUT_003 netinkamas raktas, AUT_004 tik skaitymo raktas, AUT_429 per daug bandymų, AUT_503 autentifikacija nepasiekiama (tai ne tas pats, kas blogas raktas: bandykite dar kartą), INT_003 URL, kuris nėra https, INT_403 veiksmas, kuriam reikia sesijos, INT_404 raktas ar tinklo kabliukas, kuris ne jūsų.
Kaip gauti raktą
API priklauso įmonių ir konsultavimo planams. Jei jau turite paskyrą, raktą susikursite pačioje programėlėje. Jei svarstote integraciją prieš sudarydami sutartį, parašykite support@agrogps.eu, kokią sistemą norite prijungti, ir suteiksime bandomąją prieigą. Dokumentacija vieša ir nemokama: norime, kad ją peržiūrėtumėte prieš mokėdami.
Dažniausiai užduodami klausimai
Ar galiu vesti visą žurnalą iš savo ERP neatidarydamas programėlės? Taip, registravimui ir skaitymui. Oficialus siuntimas yra tik Ispanijoje ir reikalauja žmogaus sesijos su siuntimo leidimu. Tai sąmoningas sprendimas: šis veiksmas turi teisinių pasekmių ir jo neturi paleisti automatinis procesas.
Ar duomenys mano? Taip. Visas eksportas visada nemokamas, net ir atsisakius paslaugos, o per API gaunate lygiai tą patį, ką matote ekrane, įskaitant istoriją ir pakeitimų pėdsakus.
Ar yra užklausų limitas? Įprastam ERP naudojimui paskelbtos kvotos nėra. Tinklo kabliuko bandymas ribojamas iki dvidešimties kartų vienam naudotojui ir IP kas dešimt minučių, kad niekas funkcijos nenaudotų srauto generavimui.
Kas bus, jei pakeisite API? Versija yra URL. Kol v1 paskelbta, nepašaliname laukų ir nekeičiame esamų reikšmės; nauji dalykai pridedami. Jei kada nors atsirastų v2, jos veiktų greta.
Ar MCP serveris yra npm? Dar ne. Kol kas jis paleidžiamas iš saugyklos; dėl paskelbimo dar nenuspręsta. Aukščiau pateikta konfigūracija veiks tą dieną, kai jis bus paskelbtas.
Ar tai tinka konsultantui su daug klientų? Tam skirtas advisor/portfolio: viena užklausa pasako, kurie ūkiai tvarkingi, o kurie turi neužbaigtų darbų, nereikia jungtis prie kiekvieno atskirai.