Cuando se propone conectar mediante una API a explotaciones ganaderas, empresas de piensos y organismos de verificación, es fácil empezar debatiendo «qué endpoints crear». Sin embargo, que exista una conexión técnica no significa que todos interpreten los mismos hechos de la misma manera. Si el feed_amount de la explotación se refiere a la cantidad realmente suministrada o a la comprada, si el batch_id de la empresa de piensos representa el lote de producción o la unidad entregada, o si el approved del organismo de verificación significa que se han recibido los datos o que ha terminado la verificación de la reducción, la API se convierte en un canal que propaga errores con rapidez.

Una API de datos de carbono no es una mera integración de sistemas. Es un contrato digital que intercambia quién presentó cada evidencia, qué cálculo la utilizó y quién emitió una decisión conforme a qué criterios. Primero deben definirse el significado operativo y las responsabilidades; después se diseñan las URL y el JSON.

Idea errónea: reunir todos los datos originales en una base de datos facilita la verificación

La centralización puede facilitar las búsquedas, pero no resuelve por sí sola los derechos y responsabilidades. La explotación conserva los diarios de trabajo y los datos originales de los sensores; la empresa de piensos gestiona las especificaciones de producto y los datos de los lotes; y el organismo de verificación conserva sus juicios independientes y las evidencias. Si se copian indiscriminadamente en un único lugar los originales de los que responde cada parte, quedan ambiguos cuál es la versión vigente, quién puede corregirla, qué es secreto comercial y durante cuánto tiempo debe conservarse.

Dar al organismo de verificación permisos de escritura en todos los sistemas también puede menoscabar su independencia. La persona verificadora debe examinar los materiales presentados y registrar consultas, decisiones y solicitudes de subsanación, pero no debe modificar los datos originales de la explotación ni los lotes de pienso. La API debe diseñarse para dejar claros el propietario del original y los permisos de lectura, presentación y decisión, más que para reunir todos los datos.

Además, disponer de una API no crea por sí mismo interoperabilidad. Deben coincidir los nombres de campo, las unidades, las zonas horarias, los identificadores, las transiciones de estado, la gestión de errores y las políticas de versiones. La especificación OpenAPI ofrece una descripción de interfaz neutral respecto al lenguaje que permite a personas y máquinas comprender las funciones de una API HTTP sin consultar el código fuente. No obstante, las organizaciones deben acordar por separado el significado de carbono propio del dominio.

El primer paso es separar los originales y los eventos de cada parte interesada

Los originales de la explotación incluyen la identificación de naves, sensores, animales o grupos, el número de animales, los eventos de alimentación, ventilación, limpieza y traslado, las mediciones, la calibración y el estado de los dispositivos. Los originales de la empresa de piensos incluyen códigos de producto, lotes de producción, composición y caducidad, cantidades expedidas y entregadas, instrucciones de uso e historial de cambios. Los originales del organismo de verificación incluyen el alcance, los criterios, la evaluación de materialidad, las muestras, consultas, hallazgos, decisiones y la hora de la firma.

Las tres partes no tienen que compartir toda su información interna, sino los eventos mínimos necesarios para establecer vínculos. Por ejemplo, pueden definirse eventos operativos como FeedDelivered, FeedApplied, SensorObserved, CalibrationPerformed, DataExcluded, CalculationExecuted, EvidenceSubmitted, FindingRaised y StatementVerified. Los nombres pueden variar según la implementación, pero no deben combinarse en un solo evento «el pienso fue entregado» y «el pienso fue realmente suministrado a los animales».

GS1 EPCIS es un estándar de eventos de visibilidad para compartir los eventos de la cadena de suministro mediante un lenguaje común. Su adopción no es obligatoria, pero puede servir como modelo de referencia para separar producto, lugar, tiempo y etapa operativa.

Elementos imprescindibles en un contrato común de datos

El primero son identificadores estables. Deben asignarse ID diferentes a organizaciones, explotaciones, naves, dispositivos, sensores, productos de pienso, lotes, entregas, programas de aplicación y trabajos de verificación. Los nombres visibles pueden cambiar, por lo que no deben utilizarse como claves. Los identificadores externos no deben confundirse con los ID internos, y deben registrarse la entidad emisora y el espacio de nombres.

El segundo son los valores y las unidades. No debe enviarse solo 12.3, sino también el valor, la unidad, el principio de medición, el límite de detección y el estado de calidad. La concentración en ppm y las emisiones en kg CH₄ son conceptos diferentes, por lo que deben distinguirse sus campos y esquemas. La conversión de unidades no debe sobrescribir el original y ha de conservar la fórmula y la versión empleadas.

El tercero son el tiempo y el periodo de validez. Deben distinguirse el momento de observación, el momento del evento, el momento de recepción por el sistema y el momento de corrección. Se utiliza un formato que incluya el desplazamiento UTC, como RFC 3339, y para los periodos se especifican el inicio, el final y las reglas de inclusión de los límites. El periodo de aplicación del pienso puede diferir del periodo sujeto a verificación, por lo que no deben reducirse ambos a un único campo de fecha.

El cuarto son los estados y sus transiciones. Debe definirse qué significan draft, submitted, accepted, questioned, superseded, verified y rejected, y quién puede cambiarlos. accepted puede significar únicamente que se ha superado la validación de formato, no que el contenido esté verificado. Deben documentarse la responsabilidad y las siguientes acciones permitidas para cada estado.

El quinto es el linaje. W3C PROV-O proporciona una base para expresar la Entity de los datos, la Activity que los utilizó o generó, el Agent responsable y las relaciones entre ellos. La implementación no tiene por qué usar RDF, pero puede registrar de forma coherente relaciones como derived_from, generated_by, attributed_to, method_version y source_hash. Para que un hash sea reproducible, también debe indicarse el algoritmo y si se aplica a los bytes originales o a un registro normalizado. La reducción final debe poder rastrearse hacia atrás hasta los datos originales y la ejecución del cálculo.

El sexto es el método de corrección. Si se modifican in situ los datos originales ya presentados, desaparece la versión examinada por la persona verificadora. Cuando haya un error, debe crearse una nueva versión, enlazar la anterior como superseded y registrar el motivo de la corrección y quién la aprobó. Como las solicitudes de eliminación pueden entrar en conflicto con las obligaciones legales de conservación, deben definirse por separado políticas de conservación, anonimización y bloqueo de acceso para cada tipo de dato.

Escenario de campo: 2 toneladas de pienso no equivalen a 2 toneladas de actividad de reducción

Supongamos que la empresa de piensos envía un evento de entrega de 2 toneladas de pienso con bajas emisiones de metano. El sistema de la explotación confirma la recepción, pero el registro de suministro real es de 1.7 toneladas; 0.2 toneladas permanecen en inventario y 0.1 toneladas fueron desechadas. Si la API trata la cantidad entregada como cantidad aplicada, se sobrerregistra la actividad de reducción. El organismo de verificación debe consultar la relación entre el albarán, el inventario, el diario de alimentación y el número de animales destinatarios.

En el modelo correcto, FeedDelivered y FeedApplied son eventos distintos enlazados mediante el mismo ID de lote. El evento de aplicación incluye el periodo, la nave o grupo destinatario, la cantidad, la unidad, el método de registro, la persona autora y el enlace a la evidencia. El organismo de verificación no modifica el original, sino que crea un FindingRaised para solicitar una explicación de la diferencia de 0.3 toneladas. La explotación añade eventos de inventario y desecho y crea una nueva versión del paquete presentado.

A continuación, el servicio de cálculo genera el resultado utilizando la cantidad aplicada aprobada, el periodo de medición y la versión del método. La decisión de verificación no solo hace referencia al valor resultante, sino también al paquete de evidencias utilizado y al ID de la ejecución del cálculo. Así pueden localizarse los resultados e informes afectados si posteriormente se corrigen los datos del lote de pienso o cambia la fórmula.

La autenticación y los permisos se adaptan a las acciones, no al tipo de socio

RFC 9700, publicado en 2025, recoge las prácticas recomendadas de seguridad más recientes para OAuth 2.0 y aborda medidas pertinentes contra los ataques de repetición de tokens y el diseño de límites para permisos y audiencias. En integraciones entre servidores deben separarse las identidades de organización y de carga de trabajo, y establecerse las políticas de duración de tokens y rotación de claves según el riesgo y la arquitectura del servicio.

Los permisos no deben limitarse a un único rol amplio como «usuario de empresa de piensos». Se restringen por objeto y acción, por ejemplo farm:A/read:aggregates, farm:A/write:delivery o verification:case-123/read:evidence. Las descargas masivas, el acceso a datos originales, las correcciones y las decisiones de verificación requieren permisos más elevados y quedan sujetos a auditoría. Cuando finaliza el consentimiento de la explotación o el contrato, no basta con revocar el token: también deben gestionarse los derechos de uso y conservación de las copias existentes.

Los reintentos, errores y versiones determinan la fiabilidad operativa

Como la conexión de red de la explotación puede interrumpirse con frecuencia, el reintento es un comportamiento básico. Se utilizan ID de evento y claves de idempotencia para evitar que una misma entrega u observación se registre varias veces. El servidor debe devolver con claridad el resultado del procesamiento y tratar con el mismo resultado una solicitud reenviada porque se perdió la respuesta satisfactoria. Para cargas masivas se proporcionan un ID de paquete, el éxito o fracaso de cada elemento y un punto de reanudación.

Los errores deben distinguir entre formato, permisos, duplicado, ausencia de un ID de referencia, esquema caducado y revisión pendiente, además de indicar si se puede reintentar y ofrecer un ID de correlación para el seguimiento. Estados como completed o rejected son ejemplos; la especificación real de la API debe fijar en una tabla los estados admitidos y las condiciones de transición.

Las versiones no son solo una cuestión de números en la URL. Debe definirse una política de compatibilidad para cambios en campos, valores enumerados y unidades, y mantener la documentación OpenAPI junto con el código. También deben comunicarse a los socios el calendario de retirada y el método alternativo.

Una API para organismos de verificación debe ofrecer «auditabilidad»

Verificar no consiste en comprobar que la respuesta de la API sea 200. ISO 14064-3 establece principios y requisitos para validar y verificar declaraciones de gases de efecto invernadero de organizaciones, proyectos y productos. Si existe un programa concreto, se añaden sus requisitos. Por ello, en lugar de declarar automáticamente el cumplimiento de una norma específica, la API debe proporcionar materiales que permitan a la persona verificadora evaluar los límites, criterios, evidencias, historial de cambios y errores materiales.

La vista de lectura o exportación para verificación debe incluir la instantánea del momento de la presentación, las versiones del esquema y del método, el hash de los datos originales, la lista de exclusiones, las consultas y respuestas y el historial de decisiones. Si solo se consulta el valor actual, no puede reproducirse qué se examinó en el pasado. Los datos originales de gran volumen pueden facilitarse mediante una URL firmada, una URL de acceso temporal o un paquete de datos separado, pero deben registrarse el acceso y la descarga.

Lista de comprobación para la implementación

  • ¿Se han definido los originales de los que responde cada explotación, empresa de piensos y organismo de verificación, así como los eventos compartidos?

  • ¿Se distinguen como eventos diferentes la entrega, la recepción, el suministro real, el inventario y el desecho?

  • ¿Existen ID estables para organizaciones, explotaciones, naves, dispositivos, lotes de pienso y trabajos de verificación?

  • ¿Cada valor incluye unidad, tiempo, estado de calidad y versión del método de medición o cálculo?

  • ¿Se distinguen los estados de presentación, aceptación formal, revisión del contenido y verificación terminada?

  • ¿Las correcciones quedan como una nueva versión con su motivo, en lugar de sobrescribir el original?

  • ¿Puede rastrearse desde la declaración final hasta los datos originales, las actividades y las partes responsables?

  • ¿Los permisos de los tokens se limitan al mínimo por explotación, periodo, tipo de datos y acción?

  • ¿Los reintentos y las cargas masivas evitan el cómputo duplicado?

  • ¿Están claros los códigos de error, el ID de correlación y la posibilidad de reintentar?

  • ¿Existen una especificación OpenAPI, ejemplos, avisos de cambios y pruebas de contrato del consumidor?

  • ¿Puede la persona verificadora consultar en modo de solo lectura la instantánea de la presentación y el historial de cambios?

Conclusión: una buena API preserva la responsabilidad y el significado, no solo la conexión

El éxito de una API no puede juzgarse por el número de llamadas. Debe distinguir entre entrega y aplicación, concentración y emisiones, recepción y verificación, y preservar al responsable del original de cada dato. Si no se acuerdan identificadores, unidades, tiempos, estados, linaje, correcciones y permisos, una conexión rápida solo generará confusión con rapidez.

Por tanto, el orden correcto es definir los eventos y la responsabilidad sobre las evidencias, establecer el contrato de datos, aplicar el mínimo privilegio, fijar políticas de reintentos y versiones y diseñar las instantáneas de verificación. Estándares como OpenAPI, OAuth, EPCIS y PROV son herramientas para expresar e intercambiar este contrato. El nombre de una norma específica no garantiza automáticamente la admisibilidad de una declaración de carbono. La conexión entre sistemas genera confianza cuando la API muestra sin interrupciones la cadena de evidencias conforme a la metodología y los criterios de verificación de cada programa.

Fuentes