Webhooks y API de Campodato: integra el cuaderno con tu ERP o tu báscula

Una explotación agraria mediana trabaja hoy con varios sistemas a la vez: el cuaderno de campo digital, el software de almacén o báscula de la cooperativa, el ERP contable y, en muchos casos, un TPV o un módulo de facturación propio. Cuando esos sistemas no comparten datos de forma automática, el técnico acaba reintroduciendo manualmente lo que el agricultor ya anotó, y los registros divergen. La trazabilidad que exige el RD 1054/2022 (cuaderno de explotación SIEX) y la integridad que demanda Verifactu se vuelven imposibles de mantener sin una fuente única de verdad.

Campodato está diseñado para ser ese centro de datos: el dato se anota una vez con rigor normativo y fluye hacia cualquier sistema externo mediante una API REST genérica y un motor de webhooks firmados. Este artículo describe cómo funciona esa infraestructura de integración y qué pueden hacer con ella cooperativas, gestorías e integradores.

---

Por qué una explotación mediana necesita conectar el cuaderno con su ERP

El coste oculto de la doble entrada

El Registro de Explotaciones previsto en el RD 1054/2022 obliga a anotar cada operación —tratamiento fitosanitario, fertilización, cosecha, venta— con los datos mínimos del Anexo V: producto, dosis, fecha, número de registro, parcela SIGPAC y firma. Esos mismos datos son los que el ERP necesita para registrar el gasto o el movimiento de stock, y los que la gestoría necesita para cuadrar la declaración PAC.

Cuando un agricultor anota un tratamiento en el cuaderno y el responsable de almacén de la cooperativa lo vuelve a introducir en su SGA, nace un dato duplicado con riesgo de inconsistencia. Si las cifras no cuadran —porque la báscula redondea diferente o porque uno usa kilos y el otro toneladas— el cuaderno y la factura no coinciden, y un cruce de datos de la AEAT o el MAPA puede detectar la discrepancia.

Los tres flujos de integración más habituales

• Del cuaderno al ERP: cada operación certificada en el cuaderno genera un movimiento de coste en el ERP. Cuando se sella una factura con huella Verifactu encadenada, el ERP la recibe de forma automática y cierra el ciclo contable.
• Del ERP o báscula al cuaderno: la pesada de entrada de una almazara o bodega genera la operación de cosecha en el cuaderno sin que el agricultor teclee nada. Un albarán de compra actualiza el inventario de insumos.
• Alertas de inventario: el nivel de stock de un fitosanitario baja cada vez que el cuaderno registra un tratamiento; cuando cruza el mínimo configurado, el ERP recibe la alerta y lanza la propuesta de pedido al proveedor.

Campodato no ofrece conectores preconstruidos para ERP específicos. Lo que ofrece es la infraestructura genérica —API REST segura y webhooks firmados— para que el integrador o la gestoría construya exactamente el conector que necesita, con cualquier lenguaje o plataforma.

---

La API REST de Campodato: tokens scoped, fail-closed

Tokens de API con formato y ciclo de vida definidos

Cada integración recibe un token de API con el formato cdp_<32 bytes base64url>. El prefijo cdp_ identifica el origen del secreto; el cuerpo son 32 bytes aleatorios codificados en base64url. El token se muestra en claro una sola vez en el momento del alta: Campodato almacena únicamente el hash SHA-256 del token y un prefijo visible de 12 caracteres (cdp_a1b2c3d4…) para identificarlo en la interfaz sin exponer el secreto. Si se pierde, no se puede recuperar; hay que revocar el token y crear uno nuevo.

Los tokens son revocables en cualquier momento desde el panel de integraciones. También pueden configurarse con fecha de caducidad: pasada esa fecha, el token ya no es válido aunque no se haya revocado explícitamente.

Scopes: permiso mínimo necesario

Los permisos se expresan como <módulo>:<acción>. La acción puede ser leer (equivalente a los métodos GET) o escribir (POST/PATCH). La lista vacía no autoriza nada: el diseño es fail-closed, lo que significa que un token recién creado no tiene acceso a nada hasta que se le asignan scopes explícitos.

Algunos scopes del catálogo:

El comodín *:<acción> está pensado solo para integraciones de plena confianza. Un token de báscula solo necesita inventario:escribir; uno del ERP contable necesita facturacion:leer y cuaderno:leer. La acción escribir no implica leer: cada una se concede de forma explícita e independiente.

Cómo se autentica una petición

`` Authorization: Bearer cdp_<token_en_claro> ``

El servidor calcula el hash SHA-256 del token recibido, lo compara contra la base de datos en tiempo constante (sin oráculos de temporización), verifica que no esté revocado ni caducado, resuelve la organización propietaria y comprueba que sus scopes cubran el módulo y la acción del endpoint. Si cualquier paso falla, la respuesta es 401 o 403 sin detalles que puedan usarse para enumerar tokens válidos.

Endpoints de gestión de tokens

La gestión de tokens requiere sesión de usuario (panel web), no un token de integración:

• POST /api/webhooks/tokens — crea un token; devuelve el claro una sola vez.
• GET /api/webhooks/tokens — lista los tokens activos del tenant (prefijo y scopes, sin hash).
• POST /api/webhooks/tokens/revocar — invalida un token por su identificador.

---

Webhooks: notificaciones firmadas en tiempo real

Suscripciones por evento

El integrador crea una suscripción indicando la URL HTTPS a la que Campodato enviará las notificaciones y los eventos que desea recibir. El catálogo de eventos disponibles es:

Al crear la suscripción, Campodato genera un secreto HMAC de 32 bytes hexadecimales que se muestra en claro una sola vez. El integrador lo guarda de forma segura en su sistema para verificar las firmas; Campodato almacena únicamente la versión cifrada con la master key del servidor y nunca la expone de nuevo.

Estructura del payload entregado

Todos los eventos comparten el mismo envoltorio versionado:

``json { "version": 1, "evento": "operacion.creada", "entregaId": "550e8400-e29b-41d4-a716-446655440000", "organizationId": "uuid-de-la-explotacion", "emitidoEn": "2026-06-13T08:30:00.000Z", "datos": { // Datos del hecho de dominio, forma libre por tipo de evento } } ``

El campo entregaId es el identificador de grupo de entrega: es el mismo en todos los reintentos del mismo hecho. El integrador lo usa para implementar idempotencia y evitar el doble procesado en condiciones de red inestable.

---

Seguridad: firma HMAC-SHA256 y protección anti-SSRF

Firma HMAC en cada entrega

Cada notificación lleva tres cabeceras adicionales:

La firma se calcula con HMAC-SHA256 sobre el cuerpo serializado exactamente como se envía: misma serialización, sin reordenar claves. El integrador verifica recalculando el HMAC sobre el cuerpo crudo antes de parsear el JSON, usando el secreto guardado en el alta:

```js // Node.js — verificación de firma const crypto = require('crypto')

function verificarFirma(cuerpoRaw, secreto, firmaRecibida) { const esperada = crypto .createHmac('sha256', secreto) .update(cuerpoRaw, 'utf8') .digest('hex') const a = Buffer.from(esperada, 'utf8') const b = Buffer.from(firmaRecibida, 'utf8') if (a.length !== b.length) return false return crypto.timingSafeEqual(a, b) // comparación en tiempo constante } ```

Si la firma no coincide —porque el payload fue modificado en tránsito o el secreto es incorrecto— el integrador debe responder con un código no 2xx y no procesar el evento.

Protección anti-SSRF en dos capas

Campodato aplica dos capas de protección para evitar que una suscripción mal configurada o malintencionada se use como vector de ataque hacia la red interna del servidor:

Primera capa — validación en el alta de la suscripción:

• Se exige esquema https en producción; http solo en entornos de desarrollo con flag explícito.
• Se rechazan URL con credenciales embebidas (usuario:contraseña@host).
• Se bloquean destinos privados literales: localhost, .local, .internal, *.lan, rango loopback (127.0.0.0/8, ::1), link-local (169.254.0.0/16, incluida la dirección de metadatos de nube 169.254.169.254), RFC 1918 (10/8, 172.16/12, 192.168/16) y otros rangos reservados.

Segunda capa — resolución DNS anti-rebinding en cada entrega: Un host que en el momento del alta apunta a un servidor público podría re-resolver a una IP interna en el momento de la entrega. Para bloquearlo, el dispatcher de Campodato resuelve el host por DNS justo antes de salir a red y rechaza la petición si cualquiera de las IPs resueltas cae en rangos privados o reservados. Si la validación falla, el intento queda registrado con código HTTP 0 y el motivo del bloqueo, sin que se produzca ninguna petición de red.

---

Reintentos con backoff exponencial y registro append-only

Si el endpoint del integrador devuelve un código no 2xx o no responde en 10 segundos, Campodato aplica la siguiente política de reintentos:

Tras 5 intentos fallidos la entrega queda en estado agotada. El tope máximo entre intentos es 1 hora, lo que acota el retraso total a pocas horas en el peor caso.

Cada intento queda registrado como una fila nueva en el log de entregas: Campodato nunca sobreescribe ni modifica un registro previo. El estado vigente de una entrega es el del intento de mayor número de su grupo. El integrador puede consultar el estado en cualquier momento con GET /api/webhooks/entregas/estado?suscripcionId=<id>.

---

Tres casos de uso concretos

1. Enviar una venta al ERP de la cooperativa

La cooperativa registra una suscripción al evento factura.sellada. Cada vez que un agricultor asociado emite una factura desde Campodato, la cooperativa recibe la notificación en segundos con la huella Verifactu encadenada y los datos fiscales. El ERP crea el movimiento contable sin intervención manual. Para albaranes y pedidos sin factura, el evento operacion.creada con tipo de venta aporta la misma información de forma inmediata.

2. Recibir pesadas de báscula en el cuaderno

La báscula de salida del almacén de la cooperativa tiene permiso cuaderno:escribir y inventario:escribir. Al registrar una pesada, llama a la API de Campodato con un POST que incluye el recinto SIGPAC, el cultivo, la cantidad y la fecha. Campodato anota la operación de cosecha en el cuaderno legal y ajusta el inventario de producto cosechado. El tractorista no toca ningún formulario; el dato nace en la báscula y llega al cuaderno con el rigor que exige el RD 1054/2022.

3. Alertas de inventario de insumos para la gestoría

La gestoría que asesora a varias explotaciones configura una suscripción al evento inventario.bajo_minimo para cada cliente. Cuando el cuaderno de una explotación anota un tratamiento fitosanitario y el stock del producto cruza el umbral mínimo, la gestoría recibe la alerta en su sistema de gestión y puede preparar la orden de compra antes de que el agricultor lo solicite. La misma suscripción sirve para cualquier insumo: fitosanitarios, fertilizantes, combustible para maquinaria.

---

Preguntas frecuentes

¿La API de Campodato es la misma que usa la app web? Sí. No existe una API de integración separada. Los endpoints que consume la interfaz web y la app móvil son los mismos que puede llamar el integrador con su token. Los datos que lees vía API son exactamente los que aparecen en pantalla, incluyendo los registros legales sellados del cuaderno y las facturas Verifactu inmutables.

¿Los webhooks garantizan entrega exactamente una vez? No se garantiza exactamente una vez; se garantiza al menos una vez con reintentos. El integrador debe implementar idempotencia usando el campo entregaId del payload para detectar si ya ha procesado ese hecho de dominio y descartarlo si corresponde.

¿Puedo tener varias suscripciones al mismo evento? Sí. Campodato hace fan-out: si hay tres suscripciones activas que escuchan operacion.creada, las tres reciben el mismo evento de forma independiente, cada una con su propia firma HMAC y su propio registro de entregas separado.

¿Mi endpoint puede estar detrás de una IP privada? No en producción. La protección anti-SSRF bloquea tanto las IP privadas literales como los hosts que resuelven a rangos privados. El endpoint webhook debe ser accesible desde internet. En entornos de desarrollo local, se puede usar una herramienta de túnel (como ngrok) y activar el modo permisivo de esquema HTTP con la variable de entorno correspondiente.

---

Conclusión

La API REST y los webhooks de Campodato son la infraestructura que convierte el cuaderno digital en el centro de datos de la explotación. Los tokens scoped con la política fail-closed garantizan que cada sistema externo accede solo a lo que necesita. La firma HMAC-SHA256 permite al integrador verificar la autenticidad de cada notificación sin depender de la red. La protección anti-SSRF en dos capas —validación en el alta más resolución DNS en cada entrega— protege la infraestructura del servidor frente a usos malintencionados. Y el registro append-only de entregas da al responsable técnico visibilidad completa sobre qué se entregó, cuándo y con qué resultado, sin posibilidad de reescribir el historial.

Para gestorías que gestionan múltiples explotaciones, el modelo multi-tenant con aislamiento de datos por organización garantiza que los datos de cada cliente son estrictamente inaccesibles para los demás, independientemente del token que se use.

---

Artículo elaborado por Summum Marketing para el blog de Campodato.