API, webhooks y MCP: conecta tu ERP al cuaderno

Q: ¿Qué pasa si cambiáis la API?

La versión va en la URL. Mientras v1 siga publicada, no quitamos campos ni cambiamos el significado de los que hay; lo nuevo se añade. Si algún día hubiera una v2 , convivirían.

Q: ¿Esto vale para un asesor con muchos clientes?

Para eso está advisor/portfolio : una llamada te dice qué explotaciones están al día y cuáles tienen labores incompletas, sin entrar una por una.

Actualizado: septiembre de 2026

Si llevas la explotación con un ERP, una hoja de costes o el programa de tu asesoría, no tiene sentido teclear las labores dos veces. Esta es la documentación para sacar el cuaderno, los costes y el estado de cumplimiento desde fuera, y para meter labores desde el sistema que ya usas.

La base es https://agrogps-api.fly.dev/api/v1. Está en producción desde el 17 de septiembre de 2026. Responde JSON siempre, también en los errores.

Dos formas de identificarse

Quién llama	Cabecera	Qué puede hacer
La app o la web	`Authorization: Bearer <sesión>`	Todo, incluido crear y revocar claves
Un sistema externo	`X-API-Key: agk_…`	Leer, o leer y escribir según el ámbito de la clave

La clave se crea una vez desde tu sesión y se enseña una sola vez: después solo guardamos su hash. Si la pierdes, se revoca y se crea otra. Una clave de solo lectura que intente escribir recibe 403 AUT_004. Las claves no pueden crear ni borrar otras claves ni webhooks: eso siempre va con la sesión de 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é puedes leer

Endpoint	Devuelve
`GET /farms`	Las explotaciones del titular de la clave, con su rol
`GET /sync/entries?farm_id=…&since=0`	Todas las labores con el anexo II completo, paginadas por `next`
`GET /groups/:id/overview`	Panel del grupo: labores, coste, ingresos, margen, hectáreas tratadas y cultivo por explotación
`GET /advisor/portfolio`	Cartera del asesor: qué explotaciones están al día y cuáles no
`GET /advisor/farms/:id/pending`	Los campos que faltan por rellenar, labor a labor
`GET /notebook/entries/:id/history`	Quién cambió qué y cuándo en una labor

Con una clave de escritura además puedes registrar labores con POST /sync/entries, con el mismo cuerpo que usa la app. La sincronización va por since, así que un proceso nocturno solo se trae lo que ha cambiado.

Empezar gratis

Webhooks firmados

En vez de preguntar cada cinco minutos, te avisamos. Damos de alta una URL https pública y mandamos un aviso cuando pasa algo en una explotación donde eres dueño o encargado.

Evento	Cuándo se dispara
`entry.pushed`	Se sincronizan labores y al menos una se acepta
`entry.reviewed`	Un asesor o el titular aprueba o marca una labor
`webhook.test`	Pulsas probar

Cada entrega lleva X-Agro-Event, X-Agro-Timestamp en segundos Unix y X-Agro-Signature con el HMAC-SHA256 de "<timestamp>.<cuerpo>". Comprueba las dos cosas: la firma y que el reloj no se haya ido más 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"])

Reglas de entrega, dichas claras para que no te lleves sorpresas: un intento, seis segundos de espera y sin reintentos. No seguimos redirecciones y rechazamos direcciones privadas, de enlace local y de metadatos de nube, tanto al dar de alta la URL como al resolver el DNS de cada entrega. Si tu sistema necesita garantías, usa el webhook como aviso y GET /sync/entries con since como red de seguridad: el aviso es cortesía, la API es la verdad.

MCP para asistentes de IA

La misma API está expuesta como servidor MCP, el protocolo que usan los asistentes para conectarse a herramientas. Sirve para preguntarle a un asistente cosas como qué explotaciones llevan retraso, cuánto ha costado la campaña o qué falta por rellenar antes de una inspección.

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

Herramientas disponibles: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending y record_entry. La última solo funciona con clave de escritura, queda marcada en el historial como escritura por API y nunca envía nada a la administración.

Por qué la API no sirve para hacer trampas

Una API sobre un registro con valor legal tiene que poder mirarse de frente. El RD 1054/2022 permite llevar el cuaderno con cualquier sistema informático que cumpla los requisitos del anexo II y sea interoperable con el SIEX, y deja claro que el responsable de la veracidad es el titular, no el programa. Nuestra parte es la integridad, y está puesta en el código.

Lo que alguien podría intentar	Qué hace la API
Anotar hoy con fecha de hace meses	Cada labor guarda la fecha declarada y la de llegada real al servidor, y el historial anota los días de retraso
Anotar con fecha futura	Se rechaza si supera las 24 horas desde ahora
Escribir sin una persona detrás	Toda labor lleva autor, y las que entran por clave quedan marcadas con el prefijo de esa clave
Borrar lo que estorba	No se borra nada: los borrados son lápidas con fecha
Enviar a la administración en automático	El envío oficial exige la sesión de una persona con permiso: una clave recibe `403 SIE_403`

Errores

Siempre {"code":"INT_NNN","message":"…"}, nunca una traza. Los que más vas a ver: AUT_003 clave inválida, AUT_004 clave de solo lectura, AUT_429 demasiados intentos, AUT_503 autenticación no disponible (que no es lo mismo que clave mala: reintenta), INT_003 URL que no es https, INT_403 operación que exige sesión, INT_404 clave o webhook que no es tuyo.

Cómo se consigue una clave

La API va con los planes de empresa y de asesoría. Si ya tienes cuenta, la clave se crea desde la propia app. Si estás valorando la integración antes de contratar, escribe a soporte@agrogps.eu contando qué sistema quieres conectar y te damos acceso de pruebas. La documentación es pública y gratis: preferimos que la mires antes de pagar.

Empezar gratis

Preguntas frecuentes

¿Puedo llevar el cuaderno entero desde mi ERP sin abrir la app? Sí para registrar y leer. No para el envío oficial a la administración, que exige la sesión de una persona con permiso para enviar. Es una decisión deliberada: ese acto tiene consecuencias legales y no debe dispararlo un proceso automático.

¿Los datos son míos? Sí. La exportación completa es gratis siempre, también si te das de baja, y por la API te llevas exactamente lo mismo que ves en pantalla, incluidos los históricos y el rastro de cambios.

¿Hay límite de llamadas? No hay cuota publicada para uso normal de un ERP. Probar un webhook sí está limitado a veinte veces por usuario e IP cada diez minutos, para que nadie use la función como emisor de tráfico.

¿Qué pasa si cambiáis la API? La versión va en la URL. Mientras v1 siga publicada, no quitamos campos ni cambiamos el significado de los que hay; lo nuevo se añade. Si algún día hubiera una v2, convivirían.

¿El servidor MCP está en npm? Todavía no. Hoy se ejecuta desde el repositorio; la publicación está pendiente de decidirse. La configuración de arriba es la que funcionará el día que se publique.

¿Esto vale para un asesor con muchos clientes? Para eso está advisor/portfolio: una llamada te dice qué explotaciones están al día y cuáles tienen labores incompletas, sin entrar una por una.