Introducción a Pasarela SIEX

Esta guía documenta la solución integral de Pasarela SIEX para el reporte automatizado de tratamientos fitosanitarios al Ministerio de Agricultura a través de la plataforma SIEX oficial.

Información General de la API

Autenticación Requerida

Todos los endpoints requieren las siguientes cabeceras:

• Ocp-Apim-Sid-Key: Tu clave SID específica
• Ocp-Apim-Subscription-Key: Tu clave de API

Prerequisitos Importantes

Antes de usar la API necesitas:

• Registro en el portal de desarrolladores
• Configuración de explotaciones en CXTierra
• Alta de aplicadores con códigos ROPO válidos

¿Qué es la Pasarela SIEX?

La Pasarela SIEX es una solución integral que permite a las empresas agrícolas enviar automáticamente los datos de tratamientos fitosanitarios desde sus sistemas de gestión (ERP) directamente al Ministerio de Agricultura a través de la plataforma SIEX oficial.

¿Por qué usar esta solución?

• Cumplimiento automatizado: Elimina la carga manual de reportar tratamientos fitosanitarios
• Integración transparente: Se conecta directamente con su sistema ERP existente
• Validación previa: Los datos se validan antes de enviarlos al Ministerio
• Trazabilidad completa: Registro completo de todas las operaciones realizadas

¿Cómo funciona?

El sistema actúa como intermediario inteligente entre su ERP y la plataforma SIEX del Ministerio, transformando y validando los datos según los requisitos oficiales antes de la entrega final.

Arquitectura del Sistema

Componentes del Sistema

1. API Cliente (Pasarela SIEX): Punto de entrada adaptado a las necesidades específicas de cada cliente
2. Middleware de Transformación: Procesa y adapta los datos al formato requerido por SIEX
3. Sistema de Validación: Verifica que todos los datos cumplan con las normativas del Ministerio
4. Microservicio CXTierra: Gestiona el almacenamiento y la entrega final a la Administración

Configuración Inicial

Paso 1: Registro en Portal de Desarrolladores

Para utilizar la API, necesita credenciales específicas que se obtienen del portal oficial:

1. Registrarse en https://devs.plataformatierra.es
2. Contactar con soporte para asociar su usuario a los productos correctos
3. Obtener credenciales necesarias para la integración

Paso 2: Variables de Configuración

Una vez registrado, obtendrá las siguientes credenciales:

Variable	Descripción	Entorno
CXTierraProduct	Identificador del producto API	api-cxt-siex (producción) api-cxt-siex-dev (desarrollo)
Ocp-Apim-Sid-Key	Clave SID para autenticación	Único por cliente
Ocp-Apim-Subscription-Key	Clave de API para autenticación	Único por cliente

Paso 3: Configuración en CXTierra

Antes de usar la API, debe configurarse la información base:

1. Alta de explotaciones: Registro de fincas desde SIGPAC o mediante listado de DNI (proceso manual)
2. Alta de aplicadores: Registro de todas las personas autorizadas con su código ROPO correspondiente

Estructura de Datos y Jerarquías

Modelo de Entidades

El sistema organiza la información siguiendo la estructura oficial de SIEX:

Relaciones Entre Entidades

• Explotación: Contenedor principal que agrupa toda la actividad de una campaña
• Parcelas: Ubicaciones SIGPAC donde se realizan los tratamientos
• Cultivos: Tipos y variedades específicas cultivadas en cada parcela
• Aplicadores: Personas autorizadas para realizar tratamientos (con ROPO)
• Tratamientos: Registro de aplicaciones fitosanitarias con todos sus detalles

Flujo de Trabajo Completo

Guía de Implementación Paso a Paso

Configuración Inicial (Una sola vez por campaña)

Paso 1: Obtener Credenciales

1. Registrarse en el portal de desarrolladores
2. Contactar con soporte para activación del servicio
3. Configurar variables de entorno en su sistema ERP

Paso 2: Configuración Base

1. Solicitar alta de explotaciones en CXTierra (proceso manual)
2. Registrar aplicadores con códigos ROPO válidos
3. Verificar parcelas SIGPAC están correctamente configuradas

Paso 3: Pruebas de Integración

1. Implementar autenticación con headers requeridos
2. Probar endpoint de consulta de explotación
3. Validar obtención correcta del agrifarmId

Flujo Operativo (Para cada tratamiento fitosanitario)

Paso 1: Identificar la Explotación

GET /v1/siex/farms?rea=SU_CODIGO_REA&year=2025

Objetivo: Obtener el agrifarmId y datos de la explotación

Paso 2: Generar IDs de Ubicación

POST /v1/siex/listidcp/?agrifarmId=urn:ngsi-ld:AgriFarm:1-1

Objetivo: Relacionar parcelas SIGPAC con cultivos específicos

Paso 3: Registrar el Tratamiento

POST /v1/entities/agriphytosanitarys/?agrifarmId=urn:ngsi-ld:AgriFarm:1-1

Objetivo: Reportar la aplicación fitosanitaria en la plataforma

Paso 4: Verificar el Registro

GET /v1/entities/agriphytosanitarys/?agrifarmId=urn:ngsi-ld:AgriFarm:1-1

Objetivo: Confirmar que el tratamiento se registró correctamente

Paso 5: Comunicar a la Administración

POST /v1/siex/exportCUE/?agrifarmId=urn:ngsi-ld:AgriFarm:1-1

Objetivo: Reportar oficialmente la aplicación fitosanitaria

Casos de Uso Comunes

Caso 1: Tratamiento en Múltiples Parcelas del Mismo Cultivo

Escenario: Aplicar fungicida en 5 parcelas diferentes con tomate cherry

Flujo de Trabajo:

1. Obtener IDs incluyendo todas las parcelas SIGPAC en una sola petición al endpoint /listidcp
2. Registrar una aplicación con todos los IDs obtenidos en el array idcp
3. El sistema registrará automáticamente el tratamiento para todas las ubicaciones especificadas

Ventajas: Un solo registro cubre múltiples ubicaciones, simplificando el proceso

Caso 2: Diferentes Productos en la Misma Parcela

Escenario: Aplicar herbicida por la mañana y fungicida por la tarde en la misma ubicación

Flujo de Trabajo:

1. Realizar el flujo completo para el primer producto (herbicida)
2. Repetir el proceso con los mismos IDs de ubicación para el segundo producto
3. Cada producto se registrará como una aplicación independiente con sus propios datos

Importante: Respetar intervalos mínimos entre aplicaciones según la normativa

Caso 3: Tratamiento de Emergencia

Escenario: Aplicación urgente fuera del horario normal debido a plaga detectada

Consideraciones:

• El sistema acepta registros las 24 horas del día
• La fecha de aplicación puede ser en tiempo real o retrospectiva (mismo día)
• Validación automática según el tipo de producto y urgencia
• Documentación adicional puede ser requerida para justificar la urgencia

Caso 4: Registro Retroactivo

Escenario: Registrar tratamientos realizados en días anteriores

Limitaciones:

• Máximo 7 días de retroactividad (puede variar según configuración)
• Justificación requerida para registros no inmediatos
• Validación estricta de fechas y coherencia temporal

Mejores Prácticas

Optimización de Rendimiento

Agrupar Operaciones

• Registrar múltiples parcelas en una sola aplicación cuando sea posible
• Usar el endpoint /listidcp para obtener múltiples IDs simultáneamente

Gestión de Cache

• Cachear agrifarmId durante toda la campaña
• Reutilizar IDs de cultivo-ubicación para tratamientos similares
• Implementar cache local para catálogos de productos

Rate Limiting

• Respetar límites de peticiones por minuto
• Implementar colas para múltiples registros simultáneos

Seguridad y Cumplimiento

Protección de Credenciales

• Almacenar API Keys en variables de entorno seguras
• Rotar credenciales periódicamente
• No incluir credenciales en logs

Trazabilidad Completa

• Mantener registro local de todas las operaciones
• Implementar auditoría de cambios
• Conservar evidencias de cumplimiento normativo

Validación de Datos

• Verificar datos antes de enviar a la API
• Implementar validaciones de negocio locales
• Mantener coherencia entre sistemas

Diagrama de Integración Completa

Próximos Pasos

Para comenzar a utilizar la API, consulta la documentación detallada de los endpoints:

Documentación de Endpoints

Consulta la Documentación de Endpoints para ver ejemplos detallados de cada llamada a la API.

Soporte y Recursos

Canales de Soporte

Portal de Desarrolladores

• URL: https://devs.plataformatierra.es
• Documentación técnica adicional
• Gestión de credenciales y configuración

Soporte Técnico

• Acceso a través del portal de desarrolladores
• Tickets para problemas técnicos específicos
• Asistencia en configuración inicial

Recursos Adicionales

• Catálogos oficiales de productos fitosanitarios
• Documentación de códigos SIGPAC
• Guías de buenas prácticas agrícolas

Glosario de Términos

Término	Descripción
REA	Registro de Explotaciones Agrarias
SIGPAC	Sistema de Información Geográfica de Parcelas Agrícolas
ROPO	Registro Oficial de Productos y Operadores fitosanitarios
CUE	Cuaderno Digital de Explotación
SIEX	Sistema de Información de Explotaciones agrícolas

¿Necesitas más ayuda?

Para soporte técnico adicional, accede al portal de desarrolladores en https://devs.plataformatierra.es o contacta con nuestro equipo de soporte.