API, webhooks i MCP: connecta el teu ERP al quadern

Si portes l'explotació amb un ERP, un full de costos o el programa de la teva assessoria, no té sentit teclejar les feines dues vegades. Aquesta és la documentació per treure el quadern, els costos i l'estat de compliment des de fora, i per posar-hi feines des del sistema que ja fas servir.

La base és https://agrogps-api.fly.dev/api/v1. És en producció des del 17 de setembre de 2026. Respon sempre JSON, també en els errors.

Dues maneres d'identificar-se

Qui fa la crida	Capçalera	Què pot fer
L'app o la web	`Authorization: Bearer <sesión>`	Tot, inclòs crear i revocar claus
Un sistema extern	`X-API-Key: agk_…`	Llegir, o llegir i escriure segons l'àmbit de la clau

La clau es crea una vegada des de la teva sessió i només s'ensenya una vegada: després només en guardem el hash. Si la perds, es revoca i se'n crea una altra. Una clau de només lectura que intenti escriure rep 403 AUT_004. Les claus no poden crear ni esborrar altres claus ni webhooks: això sempre va amb la sessió d'una persona.

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

Què pots llegir

Endpoint	Retorna
`GET /farms`	Les explotacions del titular de la clau, amb el seu rol
`GET /sync/entries?farm_id=…&since=0`	Totes les feines amb l'annex II complet, paginades per `next`
`GET /groups/:id/overview`	Tauler del grup: feines, cost, ingressos, marge, hectàrees tractades i cultiu per explotació
`GET /advisor/portfolio`	Cartera de l'assessor: quines explotacions estan al dia i quines no
`GET /advisor/farms/:id/pending`	Els camps que falten per omplir, feina a feina
`GET /notebook/entries/:id/history`	Qui va canviar què i quan en una feina

Amb una clau d'escriptura, a més, pots registrar feines amb POST /sync/entries, amb el mateix cos que fa servir l'app. La sincronització va per since, així que un procés nocturn només es porta el que ha canviat.

Comença gratis

Webhooks signats

En lloc de preguntar cada cinc minuts, t'avisem nosaltres. Donem d'alta una URL https pública i enviem un avís quan passa alguna cosa en una explotació on ets propietari o encarregat.

Esdeveniment	Quan es dispara
`entry.pushed`	Es sincronitzen feines i almenys una s'accepta
`entry.reviewed`	Un assessor o el titular aprova o marca una feina
`webhook.test`	Prems provar

Cada lliurament porta X-Agro-Event, X-Agro-Timestamp en segons Unix i X-Agro-Signature amb l'HMAC-SHA256 de "<timestamp>.<cuerpo>". Comprova les dues coses: la signatura i que el rellotge no s'hagi desviat més de cinc minuts.

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

Regles de lliurament, dites clares perquè no t'emportis sorpreses: un intent, sis segons d'espera i sense reintents. No seguim redireccions i rebutgem adreces privades, d'enllaç local i de metadades de núvol, tant en donar d'alta la URL com en resoldre el DNS de cada lliurament. Si el teu sistema necessita garanties, fes servir el webhook com a avís i GET /sync/entries amb since com a xarxa de seguretat: l'avís és cortesia, l'API és la veritat.

MCP per a assistents d'IA

La mateixa API està exposada com a servidor MCP, el protocol que fan servir els assistents per connectar-se a eines. Serveix per preguntar a un assistent coses com quines explotacions van endarrerides, quant ha costat la campanya o què falta per omplir abans d'una inspecció.

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

Eines disponibles: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending i record_entry. L'última només funciona amb clau d'escriptura, queda marcada a l'historial com a escriptura per API i mai no envia res a l'administració.

Per què l'API no serveix per fer trampes

Una API sobre un registre amb valor legal ha de poder mirar-se de cara. El RD 1054/2022 permet portar el quadern amb qualsevol sistema informàtic que compleixi els requisits de l'annex II i sigui interoperable amb el SIEX, i deixa clar que el responsable de la veracitat és el titular, no el programa. La nostra part és la integritat, i està posada al codi.

El que algú podria intentar	Què fa l'API
Anotar avui amb data de fa mesos	Cada feina guarda la data declarada i la d'arribada real al servidor, i l'historial anota els dies de retard
Anotar amb data futura	Es rebutja si supera les 24 hores des d'ara
Escriure sense una persona al darrere	Tota feina porta autor, i les que entren per clau queden marcades amb el prefix d'aquella clau
Esborrar el que molesta	No s'esborra res: els esborrats són làpides amb data
Enviar a l'administració en automàtic	L'enviament oficial exigeix la sessió d'una persona amb permís: una clau rep `403 SIE_403`

Errors

Sempre {"code":"INT_NNN","message":"…"}, mai una traça. Els que més veuràs: AUT_003 clau no vàlida, AUT_004 clau de només lectura, AUT_429 massa intents, AUT_503 autenticació no disponible (que no és el mateix que clau dolenta: torna-hi), INT_003 URL que no és https, INT_403 operació que exigeix sessió, INT_404 clau o webhook que no és teu.

Com s'aconsegueix una clau

L'API va amb els plans d'empresa i d'assessoria. Si ja tens compte, la clau es crea des de la mateixa app. Si estàs valorant la integració abans de contractar, escriu a support@agrogps.eu explicant quin sistema vols connectar i et donem accés de proves. La documentació és pública i gratuïta: preferim que la miris abans de pagar.

Comença gratis

Preguntes freqüents

Puc portar tot el quadern des del meu ERP sense obrir l'app? Sí per registrar i llegir. No per a l'enviament oficial a l'administració, que exigeix la sessió d'una persona amb permís per enviar. És una decisió deliberada: aquest acte té conseqüències legals i no l'ha de disparar un procés automàtic.

Les dades són meves? Sí. L'exportació completa és gratis sempre, també si et dones de baixa, i per l'API t'emportes exactament el mateix que veus a la pantalla, inclosos els històrics i el rastre de canvis.

Hi ha límit de crides? No hi ha quota publicada per a l'ús normal d'un ERP. Provar un webhook sí que està limitat a vint vegades per usuari i IP cada deu minuts, perquè ningú no faci servir la funció com a emissor de trànsit.

Què passa si canvieu l'API? La versió va a la URL. Mentre v1 continuï publicada, no traiem camps ni canviem el significat dels que hi ha; el que és nou s'afegeix. Si algun dia hi hagués una v2, conviurien.

El servidor MCP és a npm? Encara no. Avui s'executa des del repositori; la publicació està pendent de decidir-se. La configuració de dalt és la que funcionarà el dia que es publiqui.

Això serveix per a un assessor amb molts clients? Per a això hi ha advisor/portfolio: una crida et diu quines explotacions estan al dia i quines tenen feines incompletes, sense entrar-hi una per una.