API, webhooks agus MCP: ceangail do ERP leis an leabhar

Má reáchtálann tú an fheirm le ERP, le scarbhileog costas nó le bogearraí do ghnólachta comhairle, níl aon chiall le gach obair a chlóscríobh faoi dhó. Seo an doiciméadú chun an leabhar, na costais agus stádas an chomhlíonta a tharraingt amach ón taobh amuigh, agus chun obair a bhrú isteach ón gcóras atá agat cheana.

Is é an bun-URL https://agrogps-api.fly.dev/api/v1. Tá sé i dtáirgeadh ón 17 Meán Fómhair 2026. Freagraíonn sé i JSON i gcónaí, earráidí san áireamh.

Dhá bhealach le fíordheimhniú

Cruthaítear eochair uair amháin ó do sheisiún agus ní thaispeántar í ach uair amháin: ina dhiaidh sin ní choinnímid ach a hais. Má chailleann tú í, cúlghair í agus cruthaigh ceann eile. Faigheann eochair léite amháin a dhéanann iarracht scríobh 403 AUT_004. Ní féidir le heochracha eochracha ná webhooks eile a chruthú ná a scriosadh: teastaíonn seisiún duine i gcónaí chuige sin.

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

Cad is féidir leat a léamh

Le heochair scríofa is féidir leat obair a thaifeadadh freisin le POST /sync/entries, leis an gcorp céanna a úsáideann an aip. Oibríonn an sioncronú le since, mar sin ní fhaigheann post oíche ach an méid a d'athraigh.

Tosaigh saor in aisce

Webhooks sínithe

In ionad ceist a chur gach cúig nóiméad, insímid duit. Cláraíonn tú URL poiblí https agus seolaimid fógra nuair a tharlaíonn rud éigin ar fheirm ina bhfuil tú i d'úinéir nó i do bhainisteoir.

Iompraíonn gach seachadadh X-Agro-Event, X-Agro-Timestamp i soicindí Unix agus X-Agro-Signature le HMAC-SHA256 de "<timestamp>.<cuerpo>". Seiceáil an dá rud: an síniú, agus nár imigh an clog níos mó ná cúig nóiméad.

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

Rialacha an tseachadta, ráite go soiléir ionas nach mbeidh aon iontas ann: iarracht amháin, teorainn ama sé shoicind agus gan athiarrachtaí. Ní leanaimid atreoruithe, agus diúltaímid do sheoltaí príobháideacha, link-local agus meiteashonraí scamall, nuair a chláraítear an URL agus nuair a réitítear an DNS do gach seachadadh. Má theastaíonn ráthaíochtaí ó do chóras, úsáid an webhook mar fhógra agus GET /sync/entries le since mar líontán sábháilteachta: cúirtéis é an fógra, is é an API an fhírinne.

MCP do chúntóirí IS

Nochtar an API céanna mar fhreastalaí MCP, an prótacal a úsáideann cúntóirí chun ceangal le huirlisí. Is féidir leat ceisteanna a chur ar chúntóir mar cé na feirmeacha atá ar gcúl, cé mhéad a chosain an séasúr nó cad atá fós in easnamh roimh chigireacht.

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

Uirlisí ar fáil: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending agus record_entry. Ní oibríonn an ceann deireanach ach le heochair scríofa, marcáiltear sa stair é mar rud a scríobhadh tríd an API agus ní sheolann sé aon rud chuig an riarachán riamh.

Cén fáth nach féidir an API a úsáid chun caimiléireacht a dhéanamh

Caithfidh API ar bharr taifid a bhfuil luach dlíthiúil aige seasamh le scrúdú. Sa Spáinn, ligeann RD 1054/2022 an leabhar feirme a choinneáil le haon bhogearraí a chomhlíonann riachtanais Iarscríbhinn II agus atá idir-inoibritheach le SIEX, agus déanann sé soiléir gurb é an t-úinéir, ní an clár, atá freagrach as fírinne na dtaifead. Is é ár gcuidne an tsláine, agus tá sí tógtha isteach sa chód.

Earráidí

I gcónaí {"code":"INT_NNN","message":"…"}, ní rian cruaiche riamh. Na cinn is mó a fheicfidh tú: AUT_003 eochair neamhbhailí, AUT_004 eochair léite amháin, AUT_429 an iomarca iarrachtaí, AUT_503 fíordheimhniú gan fáil (ní hionann é agus droch-eochair: bain triail eile as), INT_003 URL nach https é, INT_403 oibríocht a dteastaíonn seisiún uaithi, INT_404 eochair nó webhook nach leatsa.

Conas eochair a fháil

Tagann an API leis na pleananna gnó agus comhairle. Má tá cuntas agat cheana, cruthaíonn tú an eochair ón aip féin. Má tá tú ag measúnú an chomhtháthaithe sula gcláraíonn tú, scríobh chuig support@agrogps.eu ag insint dúinn cén córas is mian leat a cheangal agus tabharfaimid rochtain tástála duit. Tá an doiciméadú poiblí agus saor in aisce: b'fhearr linn go léifeá é sula n-íocann tú.

Tosaigh saor in aisce

Ceisteanna coitianta

An féidir liom an leabhar ar fad a reáchtáil ó mo ERP gan an aip a oscailt? Is féidir chun taifeadadh agus léamh. Ní féidir don seoladh oifigiúil chuig an riarachán, nach bhfuil ann ach sa Spáinn agus a dteastaíonn seisiún duine le cead seolta uaidh. Tá sé sin d'aon ghnó: tá iarmhairtí dlíthiúla ag an ngníomh agus níor chóir do phróiseas uathoibríoch é a spreagadh.

An liomsa na sonraí? Is leat. Bíonn an easpórtáil iomlán saor in aisce i gcónaí, fiú má chealaíonn tú, agus tríd an API tógann tú leat go díreach a bhfeiceann tú ar an scáileán, an stair agus rian na n-athruithe san áireamh.

An bhfuil teorainn ráta ann? Níl aon chuóta foilsithe do ghnáthúsáid ERP. Tá tástáil webhook teoranta go fiche uair in aghaidh an úsáideora agus an IP gach deich nóiméad, ionas nach n-úsáideann aon duine an ghné chun trácht a ghiniúint.

Cad a tharlaíonn má athraíonn sibh an API? Tá an leagan san URL. Fad a bhíonn v1 foilsithe ní bhainimid réimsí ná ní athraímid brí na gcinn atá ann; cuirtear rudaí nua leis. Má bhíonn v2 ann riamh, beidh an dá cheann ann le chéile.

An bhfuil an freastalaí MCP ar npm? Níl fós. Inniu ritheann sé ón stór; tá an foilsiú fós le socrú. Is í an chumraíocht thuas an ceann a oibreoidh an lá a fhoilseofar é.

An oibríonn sé seo do chomhairleoir le go leor custaiméirí? Sin é an fáth a bhfuil advisor/portfolio ann: insíonn glao amháin duit cé na feirmeacha atá cothrom le dáta agus cé acu a bhfuil obair neamhiomlán acu, gan iad a oscailt ceann ar cheann.