API, webhooks u MCP: qabbad l-ERP tiegħek mar-reġistru

Jekk tmexxi r-razzett b'ERP, b'spreadsheet tal-ispejjeż jew bis-software tal-kumpanija tal-konsulenza tiegħek, m'hemmx sens li tikteb kull xogħol darbtejn. Din hija d-dokumentazzjoni biex toħroġ ir-reġistru, l-ispejjeż u l-istat tal-konformità minn barra, u biex iddaħħal xogħol mis-sistema li diġà għandek.

L-URL bażi huwa https://agrogps-api.fly.dev/api/v1. Ilu fil-produzzjoni mis-17 ta' Settembru 2026. Dejjem iwieġeb f'JSON, inklużi l-iżbalji.

Żewġ modi biex tawtentika

Ċavetta tinħoloq darba mis-sessjoni tiegħek u tintwera darba biss: wara nżommu biss il-hash tagħha. Jekk titlifha, irrevokaha u oħloq oħra. Ċavetta ta' qari biss li tipprova tikteb tirċievi 403 AUT_004. Iċ-ċwievet ma jistgħux joħolqu jew iħassru ċwievet jew webhooks oħra: għal dan dejjem trid is-sessjoni ta' persuna.

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

X'tista' taqra

B'ċavetta tal-kitba tista' wkoll tirreġistra xogħol b'POST /sync/entries, bl-istess body li tuża l-app. Is-sinkronizzazzjoni taħdem b'since, għalhekk xogħol bil-lejl iġib biss dak li nbidel.

Ibda b'xejn

Webhooks iffirmati

Minflok ma tistaqsi kull ħames minuti, ngħidulek aħna. Tirreġistra URL pubbliku https u nibagħtu avviż meta jiġri xi ħaġa f'razzett fejn int sid jew maniġer.

Kull kunsinna ġġorr X-Agro-Event, X-Agro-Timestamp f'sekondi Unix u X-Agro-Signature bl-HMAC-SHA256 ta' "<timestamp>.<cuerpo>". Iċċekkja ż-żewġ affarijiet: il-firma, u li l-arloġġ ma ċċaqlaqx aktar minn ħames minuti.

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

Ir-regoli tal-kunsinna, miktuba ċar biex ma jkunx hemm sorpriżi: tentattiv wieħed, limitu ta' ħin ta' sitt sekondi u l-ebda tentattiv ieħor. Ma nsegwux redirects, u nirrifjutaw indirizzi privati, link-local u tal-metadata tal-cloud, kemm meta jiġi rreġistrat l-URL kif ukoll meta jiġi solvut id-DNS għal kull kunsinna. Jekk is-sistema tiegħek għandha bżonn garanziji, uża l-webhook bħala avviż u GET /sync/entries b'since bħala x-xibka tas-sigurtà: l-avviż huwa kortesija, l-API hija l-verità.

MCP għall-assistenti tal-IA

L-istess API hija esposta bħala server MCP, il-protokoll li jużaw l-assistenti biex jikkonnettjaw ma' għodod. Tista' tistaqsi lil assistent affarijiet bħal liema rziezet huma lura, kemm swiet l-istaġun jew x'għadu nieqes qabel spezzjoni.

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

Għodod disponibbli: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending u record_entry. L-aħħar waħda taħdem biss b'ċavetta tal-kitba, hija mmarkata fl-istorja bħala miktuba permezz tal-API u qatt ma tibgħat xejn lill-amministrazzjoni.

Għaliex l-API ma tistax tintuża biex tqarraq

API fuq reġistru b'valur legali trid iżżomm quddiem l-iskrutinju. Fi Spanja, RD 1054/2022 jippermetti li r-reġistru tar-razzett jinżamm b'kull software li jissodisfa r-rekwiżiti tal-Anness II u li huwa interoperabbli mas-SIEX, u jagħmilha ċara li s-sid, mhux il-programm, huwa responsabbli għall-verità tar-reġistrazzjonijiet. Is-sehem tagħna huwa l-integrità, u hija mibnija fil-kodiċi.

Żbalji

Dejjem {"code":"INT_NNN","message":"…"}, qatt stack trace. Dawk li se tara l-aktar: AUT_003 ċavetta invalida, AUT_004 ċavetta ta' qari biss, AUT_429 wisq tentattivi, AUT_503 l-awtentikazzjoni mhix disponibbli (mhux l-istess bħal ċavetta ħażina: erġa' pprova), INT_003 URL li mhuwiex https, INT_403 operazzjoni li teħtieġ sessjoni, INT_404 ċavetta jew webhook li mhumiex tiegħek.

Kif tikseb ċavetta

L-API tiġi mal-pjanijiet tan-negozju u tal-konsulenza. Jekk diġà għandek kont, toħloq iċ-ċavetta mill-app stess. Jekk qed tevalwa l-integrazzjoni qabel ma tirreġistra, ikteb lil support@agrogps.eu u għidilna liema sistema trid tqabbad u nagħtuk aċċess tat-test. Id-dokumentazzjoni hija pubblika u b'xejn: nippreferu li taqraha qabel ma tħallas.

Ibda b'xejn

Mistoqsijiet frekwenti

Nista' nmexxi r-reġistru kollu mill-ERP tiegħi mingħajr ma niftaħ l-app? Iva biex tirreġistra u taqra. Le għall-kunsinna uffiċjali lill-amministrazzjoni, li teżisti biss fi Spanja u teħtieġ is-sessjoni ta' persuna bil-permess li tibgħat. Dan huwa apposta: l-att għandu konsegwenzi legali u m'għandux jinxtegħel minn proċess awtomatiku.

Id-data hija tiegħi? Iva. L-esportazzjoni sħiħa hija dejjem b'xejn, anke jekk tikkanċella, u permezz tal-API tieħu eżattament dak li tara fuq l-iskrin, inklużi l-istorja u t-traċċa tal-bidliet.

Hemm limitu tar-rata? M'hemmx kwota ppubblikata għall-użu normali ta' ERP. It-test ta' webhook huwa limitat għal għoxrin darba għal kull utent u IP kull għaxar minuti, biex ħadd ma juża l-funzjoni biex jiġġenera traffiku.

X'jiġri jekk tibdlu l-API? Il-verżjoni tinsab fl-URL. Sakemm v1 tkun ippubblikata ma nneħħux oqsma u ma nbiddlux it-tifsira ta' dawk eżistenti; jiżdiedu affarijiet ġodda. Jekk xi darba jkun hemm v2, it-tnejn jeżistu flimkien.

Is-server MCP jinsab fuq npm? Għadu le. Illum jaħdem mir-repożitorju; il-pubblikazzjoni għadha trid tiġi deċiża. Il-konfigurazzjoni ta' hawn fuq hija dik li se taħdem il-jum li jiġi ppubblikat.

Dan jaħdem għal konsulent b'ħafna klijenti? Għalhekk hemm advisor/portfolio: sejħa waħda tgħidlek liema rziezet huma aġġornati u liema għandhom xogħlijiet mhux kompluti, mingħajr ma tiftaħhom wieħed wieħed.