API, webhooks e MCP: conecta o teu ERP ao caderno
Se levas a explotación cun ERP, unha folla de custos ou o programa da túa asesoría, non ten sentido teclear os labores dúas veces. Esta é a documentación para sacar o caderno, os custos e o estado de cumprimento desde fóra, e para meter labores desde o sistema que xa usas.
A base é https://agrogps-api.fly.dev/api/v1. Está en produción desde o 17 de setembro de 2026. Responde sempre JSON, tamén nos erros.
Dúas formas de identificarse
| Quen chama | Cabeceira | Que pode facer |
|---|---|---|
| A app ou a web | Authorization: Bearer <sesión> | Todo, incluído crear e revogar chaves |
| Un sistema externo | X-API-Key: agk_… | Ler, ou ler e escribir segundo o ámbito da chave |
A chave créase unha vez desde a túa sesión e só se ensina unha vez: despois só gardamos o seu hash. Se a perdes, revógase e créase outra. Unha chave de só lectura que tente escribir recibe 403 AUT_004. As chaves non poden crear nin borrar outras chaves nin webhooks: iso sempre vai coa sesión dunha persoa.
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"}'Que podes ler
| Endpoint | Devolve |
|---|---|
GET /farms | As explotacións do titular da chave, co seu rol |
GET /sync/entries?farm_id=…&since=0 | Todos os labores co anexo II completo, paxinados por next |
GET /groups/:id/overview | Panel do grupo: labores, custo, ingresos, marxe, hectáreas tratadas e cultivo por explotación |
GET /advisor/portfolio | Carteira do asesor: que explotacións están ao día e cales non |
GET /advisor/farms/:id/pending | Os campos que faltan por encher, labor a labor |
GET /notebook/entries/:id/history | Quen cambiou que e cando nun labor |
Cunha chave de escritura ademais podes rexistrar labores con POST /sync/entries, co mesmo corpo que usa a app. A sincronización vai por since, así que un proceso nocturno só trae o que cambiou.
Webhooks asinados
En vez de preguntar cada cinco minutos, avisámoste nós. Damos de alta unha URL https pública e mandamos un aviso cando pasa algo nunha explotación onde es dono ou encargado.
| Evento | Cando se dispara |
|---|---|
entry.pushed | Sincronízanse labores e polo menos un acéptase |
entry.reviewed | Un asesor ou o titular aproba ou marca un labor |
webhook.test | Premes probar |
Cada entrega leva X-Agro-Event, X-Agro-Timestamp en segundos Unix e X-Agro-Signature co HMAC-SHA256 de "<timestamp>.<cuerpo>". Comproba as dúas cousas: a sinatura e que o reloxo non se desviase máis de cinco minutos.
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"])Regras de entrega, ditas claras para que non leves sorpresas: un intento, seis segundos de espera e sen reintentos. Non seguimos redireccións e rexeitamos enderezos privados, de ligazón local e de metadatos de nube, tanto ao dar de alta a URL como ao resolver o DNS de cada entrega. Se o teu sistema precisa garantías, usa o webhook como aviso e GET /sync/entries con since como rede de seguridade: o aviso é cortesía, a API é a verdade.
MCP para asistentes de IA
A mesma API está exposta como servidor MCP, o protocolo que usan os asistentes para conectarse a ferramentas. Serve para preguntarlle a un asistente cousas como que explotacións levan atraso, canto custou a campaña ou que falta por encher antes dunha inspección.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Ferramentas dispoñibles: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending e record_entry. A última só funciona con chave de escritura, queda marcada no historial como escritura por API e nunca envía nada á administración.
Por que a API non serve para facer trampas
Unha API sobre un rexistro con valor legal ten que poder mirarse de fronte. O RD 1054/2022 permite levar o caderno con calquera sistema informático que cumpra os requisitos do anexo II e sexa interoperable co SIEX, e deixa claro que o responsable da veracidade é o titular, non o programa. A nosa parte é a integridade, e está posta no código.
| O que alguén podería intentar | Que fai a API |
|---|---|
| Anotar hoxe con data de hai meses | Cada labor garda a data declarada e a de chegada real ao servidor, e o historial anota os días de atraso |
| Anotar con data futura | Rexéitase se supera as 24 horas desde agora |
| Escribir sen unha persoa detrás | Todo labor leva autor, e os que entran por chave quedan marcados co prefixo desa chave |
| Borrar o que estorba | Non se borra nada: os borrados son lápidas con data |
| Enviar á administración en automático | O envío oficial esixe a sesión dunha persoa con permiso: unha chave recibe 403 SIE_403 |
Erros
Sempre {"code":"INT_NNN","message":"…"}, nunca unha traza. Os que máis vas ver: AUT_003 chave non válida, AUT_004 chave de só lectura, AUT_429 demasiados intentos, AUT_503 autenticación non dispoñible (que non é o mesmo que chave mala: téntao de novo), INT_003 URL que non é https, INT_403 operación que esixe sesión, INT_404 chave ou webhook que non é teu.
Como se consegue unha chave
A API vai cos plans de empresa e de asesoría. Se xa tes conta, a chave créase desde a propia app. Se estás a valorar a integración antes de contratar, escribe a support@agrogps.eu contando que sistema queres conectar e dámosche acceso de probas. A documentación é pública e de balde: preferimos que a mires antes de pagar.
Preguntas frecuentes
Podo levar o caderno enteiro desde o meu ERP sen abrir a app? Si para rexistrar e ler. Non para o envío oficial á administración, que esixe a sesión dunha persoa con permiso para enviar. É unha decisión deliberada: ese acto ten consecuencias legais e non debe disparalo un proceso automático.
Os datos son meus? Si. A exportación completa é de balde sempre, tamén se te dás de baixa, e pola API levas exactamente o mesmo que ves na pantalla, incluídos os históricos e o rastro de cambios.
Hai límite de chamadas? Non hai cota publicada para o uso normal dun ERP. Probar un webhook si está limitado a vinte veces por usuario e IP cada dez minutos, para que ninguén use a función como emisor de tráfico.
Que pasa se cambiades a API? A versión vai na URL. Mentres v1 siga publicada, non quitamos campos nin cambiamos o significado dos que hai; o novo engádese. Se algún día houbese unha v2, convivirían.
O servidor MCP está en npm? Aínda non. Hoxe execútase desde o repositorio; a publicación está pendente de decidirse. A configuración de enriba é a que funcionará o día que se publique.
Isto vale para un asesor con moitos clientes? Para iso está advisor/portfolio: unha chamada dite que explotacións están ao día e cales teñen labores incompletos, sen entrar unha por unha.