Documentación API - Pasarela SIEX

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

Tabla de Contenidos

Introducción General
Arquitectura del Sistema
Configuración Inicial
Estructura de Datos y Jerarquías
Flujo de Trabajo Completo
Endpoints de la API
Guía de Implementación
Casos de Uso Comunes
Manejo de Errores
Mejores Prácticas
Soporte y Recursos

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

Introducción General

¿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

API Cliente (Pasarela SIEX): Punto de entrada adaptado a las necesidades específicas de cada cliente
Middleware de Transformación: Procesa y adapta los datos al formato requerido por SIEX
Sistema de Validación: Verifica que todos los datos cumplan con las normativas del Ministerio
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:

Registrarse en https://devs.plataformatierra.es
Contactar con soporte para asociar su usuario a los productos correctos
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:

Alta de explotaciones: Registro de fincas desde SIGPAC o mediante listado de DNI (proceso manual)
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

Endpoints de la API

Autenticación y Headers

Todas las peticiones requieren los siguientes headers:

http

Ocp-Apim-Sid-Key: {Ocp-Apim-Sid-Key}
Ocp-Apim-Subscription-Key: {Ocp-Apim-Subscription-Key}

1. Obtener Datos de Explotación

GET /farms

Descripción Funcional

Recupera la información completa de una explotación/campaña utilizando el código REA y el año de campaña. Este endpoint proporciona todos los datos necesarios para la integración, incluyendo parcelas SIGPAC, información geográfica y metadatos de configuración.

Cuándo Usarlo

Configuración inicial de cada campaña
Validación de que la explotación está correctamente registrada
Obtención del identificador principal (agrifarmId) necesario para todas las operaciones
Consulta de parcelas disponibles y su configuración SIGPAC

Endpoint

http

GET /v1/siex/farms?rea={codigo_rea}&year={año_campaña}

Parámetros

Parámetro	Tipo	Descripción	Ejemplo
`rea`	String	Código REA de la explotación	"1234t1234D"
`year`	Integer	Año de la campaña	2025

Información Devuelta para Explotación

La respuesta incluye información completa sobre:

Datos Básicos de la Explotación

Identificador único del sistema (id)
Nombre y descripción de la explotación
Año de campaña y fechas de registro
Información de contacto y dirección

Información del Propietario

Datos del titular de la explotación
Información de contacto completa
Identificadores oficiales (NIF, etc.)

Parcelas y Ubicaciones SIGPAC

Lista completa de parcelas registradas
Coordenadas geográficas de cada parcela
Códigos SIGPAC detallados por recinto
Superficie y características de cada ubicación

Atributos Regionales

Códigos administrativos (provincia, comunidad)
Registros oficiales (REA, REGEPA)
Información de localización específica

Respuesta Simplificada (Campos Principales)

json

[
  {
    "id": "urn:ngsi-ld:AgriFarm:1-1",
    "name": "Explotación Tomates 2025",
    "description": "Campaña de tomates temporada 2025",
    "year": 2025,
    "dateCreated": "18-04-2023 08:22:48",
    "address": {
      "addressLocality": "Urueñas",
      "addressCountry": "ES"
    },
    "owned": {
      "name": "Propietario",
      "surname": "de la Explotación",
      "email": "email@example.com",
      "nif": "12345678Z"
    },
    "agriCrop": [
      {
        "id": "urn:ngsi-ld:AgriCrop:1",
        "crop": {
          "type": "TypeCropVariety",
          "typecrop": {
            "type": "TypeCrop",
            "id": "109",
            "name": "Manzano"
          },
          "code": 1,
          "name": "Roja de narbarte"
        },
        "agriParcel": [
          {
            "id": "urn:ngsi-ld:AgriParcel:1",
            "name": "Parcela Norte",
            "sigpac": [
              {
                "idcp": 1,
                "prov": "24",
                "town": "90",
                "aggr": "0",
                "zone": "0",
                "pol": "409",
                "parc": "37",
                "enc": "5",
                "dimension": "25.44"
              }
            ]
          }
        ]
      }
    ],
    "regionalAttributes": [
      {
        "rea": "1234t1234D",
        "address": {
          "province": "León",
          "community": {
            "name": "Castilla Y León"
          }
        }
      }
    ]
  }
]

Información Clave de la Respuesta

id: Identificador único que usará como agrifarmId en todas las operaciones posteriores
agriCrop: Lista de cultivos de la explotacion
agriCrop.agriParcel: Lista de parcelas con sus códigos SIGPAC en las que se encuentra el cultivo.
agriCrop.agriParcel.idcp: Identificardor único que relaciona la parcela con el cultivo para poder registrar los tratamiento fitosanitarios.
regionalAttributes.rea: Confirmación del código REA consultado
year: Confirmación del año de campaña

2. Obtener IDs de Cultivo-Ubicación

POST /listidcp

Descripción de IDs Cultivo-Ubicación

Genera los identificadores específicos necesarios para registrar tratamientos fitosanitarios. Este endpoint relaciona las parcelas SIGPAC con los tipos de cultivo y variedades específicas, creando los vínculos únicos que se utilizarán al reportar cada aplicación.

Cuándo Usar IDs Cultivo-Ubicación

Antes de cada tratamiento para obtener los IDs correctos
Validar combinaciones de parcela + cultivo configuradas
Agrupar tratamientos por tipo de cultivo y ubicación
Verificar disponibilidad de parcelas para cultivos específicos

Endpoint de IDs

http

POST /v1/siex/listidcp/?agrifarmId={agrifarm_id}

Estructura de Petición para IDs

json

{
  "type": "IDCP",
  "crop": {
    "type": "TypeCropVariety",
    "typecrop": {
      "id": "197",
      "type": "TypeCrop",
      "name": "Tomate"
    },
    "code": 8,
    "name": "Cherry"
  },
  "regionalAttributes": [
    {
      "sigpac": [
        {
          "prov": "24",
          "town": "90",
          "aggr": "0",
          "zone": "0",
          "pol": "411",
          "parc": "23",
          "enc": "1"
        },
        {
          "prov": "24",
          "town": "90",
          "aggr": "0",
          "zone": "0",
          "pol": "412",
          "parc": "23",
          "enc": "1"
        }
      ]
    }
  ]
}

Catálogos de Referencia

Información de Cultivos

Campo	Descripción	Fuente
`typecrop.id`	Código oficial del cultivo	Catálogo SIEX del Ministerio
`typecrop.name`	Nombre del cultivo	"Tomate", "Maíz", "Trigo", etc.
`code`	Código de la variedad	Catálogo de variedades por cultivo
`name`	Nombre de la variedad	"Cherry", "Pera", "Rama", etc.

Códigos SIGPAC

Campo	Descripción	Ejemplo
`prov`	Código de provincia	"24" (León)
`town`	Código de municipio	"90"
`aggr`	Agregado	"0"
`zone`	Zona	"0"
`pol`	Polígono	"411"
`parc`	Parcela	"23"
`enc`	Recinto	"1"

Respuesta de IDs Cultivo-Ubicación

json

{
  "agrifarmId": "urn:ngsi-ld:AgriFarm:1-1",
  "crop": {
    "typecrop": {
      "id": "197",
      "name": "Tomate"
    },
    "code": 8,
    "name": "Cherry"
  },
  "idcp": [
    {
      "idcp": 1,
      "prov": "24",
      "town": "90",
      "aggr": "0",
      "zone": "0",
      "pol": "409",
      "parc": "37",
      "enc": "5"
    },
    {
      "idcp": 2,
      "prov": "24",
      "town": "90",
      "aggr": "0",
      "zone": "0",
      "pol": "410",
      "parc": "37",
      "enc": "5"
    }
  ]
}

Uso de los IDs Devueltos

Cada ID representa una combinación única de cultivo + ubicación SIGPAC
Use estos IDs en el array idcp al registrar tratamientos
Los IDs son válidos durante toda la campaña para esa combinación específica
Reutilice los IDs para múltiples tratamientos en las mismas ubicaciones

3. Registrar Aplicación Fitosanitaria

POST /agriphytosanitarys

Descripción del Registro

Registra la aplicación de un producto fitosanitario en las ubicaciones especificadas en la plataforma.

Cuándo Registrar Tratamientos

Inmediatamente después de realizar un tratamiento fitosanitario
Para documentar la actividad fitosanitaria de la explotación

Endpoint de Registro

http

POST /v1/entities/agriphytosanitarys/?agrifarmId={agrifarm_id}

Query Params Opcionales

exported = 0

exported es un integer que 0 representa NO exportados y 1 representa SI exportados.

Estructura de la Petición

json

{
  "type": "AgriPhytosanitary",
  "dateApplication": "18-06-2025 14:30:00",
  "subtype": {
    "type": "TypePhytosanitary",
    "name": "Spotter WG",
    "code": "ES-00261"
  },
  "dose": 7.0,
  "measure": {
    "type": "Measure",
    "name": "Kilogramo por hectárea",
    "symbol": "kg/ha",
    "code": 17
  },
  "idcp": ["1", "2"],
  "applicator": {
    "user": {
      "type": "UserMetadata",
      "nif": "12345678Z",
      "ropo": "ES-12345678"
    }
  }
}

Detalles de los Campos

Información Temporal

dateApplication: Fecha y hora exacta de la aplicación (formato: "DD-MM-YYYY HH:mm:ss")
- Importante: Debe ser una fecha reciente y coherente
- Validación: El sistema verifica que sea una fecha válida

Información del Producto Fitosanitario

subtype.name: Nombre comercial exacto del producto
subtype.code: Código oficial del producto en el registro SIEX
- Formato: "ES-XXXXX" para productos registrados en España
- Validación: Debe existir en el catálogo oficial de productos autorizados

Información de Dosificación

dose: Cantidad numérica de producto aplicada
measure.symbol: Unidad de medida estándar (kg/ha, l/ha, g/ha, etc.)
measure.code: Código numérico de la unidad de medida
- Validación: La dosis debe estar dentro de los límites autorizados para el producto

Información del Aplicador

applicator.user.nif: DNI/NIF del aplicador
applicator.user.ropo: Número ROPO del aplicador autorizado
- Formato: "ES-XXXXXXXX" para aplicadores españoles
- Validación: El ROPO debe estar vigente y autorizado

Ubicaciones de Aplicación

idcp: Array de identificadores obtenidos del endpoint anterior
- Origen: Resultado del endpoint /listidcp
- Uso: Define exactamente dónde se aplicó el tratamiento

Validaciones Automáticas del Sistema

El sistema realiza las siguientes verificaciones antes de aceptar el registro:

✅ Validaciones de Producto

Producto fitosanitario autorizado y vigente
Dosis dentro de los límites legales establecidos
Compatibilidad con el cultivo especificado

✅ Validaciones de Aplicador

ROPO válido y no suspendido
Autorización vigente para el tipo de producto
Datos de identificación correctos

✅ Validaciones de Ubicación

IDs de cultivo-ubicación válidos y activos
Parcelas correctamente configuradas en SIGPAC
Cultivos apropiados para el producto aplicado

✅ Validaciones Temporales

Fecha de aplicación dentro del rango válido
Coherencia con períodos de aplicación autorizados
Respeto a intervalos mínimos entre aplicaciones

Respuesta del Sistema

En caso de éxito, el sistema devuelve:

json

[
  {
    "id": "urn:ngsi-ld:AgriPhytosanitary:2903",
    "type": "AgriPhytosanitary",
    "dateCreated": "",
    "dateModified": "",
    "subtype": {
      "type": "TypePhytosanitary",
      "id": 2899,
      "subtype": {
        "type": "SubtypePhytosanitary",
        "id": 1753,
        "idpdf": "96573",
        "code": "ES-00261",
        "comp": {
          "type": "Company",
          "id": 60,
          "name": "Trade Corporation International, S.a.u.",
          "nif": "A46715413"
        },
        "subs": {
          "type": "Substance",
          "id": "818",
          "name": "Kresoxim-Metil 25% + Difenoconazol 12,5% [Wg] P/P"
        },
        "detail": "",
        "ci": []
      },
      "name": "Spotter Wg",
      "tpd": [
        {
          "type": "TPD",
          "id": 2966,
          "idate": "30-06-2017",
          "edate": "15-03-2026",
          "ldate": ""
        }
      ],
      "prod": {
        "type": "TypeProduct",
        "id": 1,
        "name": "Producto fitosanitario registrado"
      }
    },
    "dose": "7",
    "typerisk": {
      "type": "TypeRisk",
      "id": "3",
      "name": "Medio",
      "detail": ""
    },
    "infection": null,
    "detail": null,
    "tj": [],
    "idtpismv": [],
    "distributed": "0",
    "reviewed": "0",
    "exported": "0",
    "batch": "",
    "soup": "0",
    "measure": null,
    "dt": "0",
    "mdt": null,
    "st": "0",
    "mst": null,
    "efficacy": {
      "type": "TypeEfficacy",
      "id": "1",
      "name": "Buena",
      "detail": ""
    },
    "preventive": "0",
    "pp": "0",
    "speed": "0",
    "recipe": "0",
    "surface": "0",
    "entrylimit": "0",
    "seclimit": "0",
    "machine": [],
    "idcp": ["1"],
    "regionalAttributes": [{}]
  }
]

Confirmación del registro en CXTierra
Identificador único del tratamiento registrado
Confirmación de envío a la plataforma SIEX del Ministerio

4. Consultar Aplicaciones Registradas

GET /agriphytosanitarys

Descripción de Consulta

Recupera el historial completo de todas las aplicaciones fitosanitarias registradas para una explotación específica durante la campaña actual. Proporciona información detallada para auditorías, reportes y seguimiento de la actividad fitosanitaria.

Cuándo Consultar Aplicaciones

Generar reportes de tratamientos realizados en un período
Verificar registros después de realizar aplicaciones
Preparar auditorías internas o inspecciones oficiales
Analizar patrones de uso de productos fitosanitarios
Comprobar cumplimiento de las obligaciones de reporte

Endpoint de Consulta

http

GET /v1/entities/agriphytosanitarys/?agrifarmId={agrifarm_id}

Parámetros Opcionales

Parámetro	Descripción	Ejemplo
`dateFrom`	Fecha inicio consulta	"01-01-2025"
`dateTo`	Fecha fin consulta	"31-12-2025"
`product`	Filtrar por producto específico	"ES-00261"

Respuesta del sistema

json

[
  {
    "id": "urn:ngsi-ld:AgriPhytosanitary:2903",
    "type": "AgriPhytosanitary",
    "dateCreated": "",
    "dateModified": "",
    "subtype": {
      "type": "TypePhytosanitary",
      "id": 2899,
      "subtype": {
        "type": "SubtypePhytosanitary",
        "id": 1753,
        "idpdf": "96573",
        "code": "ES-00261",
        "comp": {
          "type": "Company",
          "id": 60,
          "name": "Trade Corporation International, S.a.u.",
          "nif": "A46715413"
        },
        "subs": {
          "type": "Substance",
          "id": "818",
          "name": "Kresoxim-Metil 25% + Difenoconazol 12,5% [Wg] P/P"
        },
        "detail": "",
        "ci": []
      },
      "name": "Spotter Wg",
      "tpd": [
        {
          "type": "TPD",
          "id": 2966,
          "idate": "30-06-2017",
          "edate": "15-03-2026",
          "ldate": ""
        }
      ],
      "prod": {
        "type": "TypeProduct",
        "id": 1,
        "name": "Producto fitosanitario registrado"
      }
    },
    "dose": "7",
    "typerisk": {
      "type": "TypeRisk",
      "id": "3",
      "name": "Medio",
      "detail": ""
    },
    "infection": null,
    "detail": null,
    "tj": [],
    "idtpismv": [],
    "distributed": "0",
    "reviewed": "0",
    "exported": "0",
    "batch": "",
    "soup": "0",
    "measure": null,
    "dt": "0",
    "mdt": null,
    "st": "0",
    "mst": null,
    "efficacy": {
      "type": "TypeEfficacy",
      "id": "1",
      "name": "Buena",
      "detail": ""
    },
    "preventive": "0",
    "pp": "0",
    "speed": "0",
    "recipe": "0",
    "surface": "0",
    "entrylimit": "0",
    "seclimit": "0",
    "machine": [],
    "idcp": ["1"],
    "regionalAttributes": [{}]
  }
]

Información Devuelta en Consulta

La respuesta incluye para cada aplicación registrada:

Datos del Tratamiento

Fecha y hora de aplicación
Producto utilizado y código oficial
Dosis aplicada y unidad de medida
Ubicaciones tratadas (códigos SIGPAC)

Datos del Aplicador

Identificación del aplicador (NIF)
Número ROPO y autorización
Fecha de registro del tratamiento

Metadatos del Sistema

Identificador único del registro
Estado de envío a SIEX
Fechas de creación y modificación

5. Exportar CUE

POST /exportCUE

Descripción de Exportación CUE

Registra oficialmente la aplicación de un producto fitosanitario. Este endpoint realiza todas las validaciones necesarias según la normativa del Ministerio y registra el tratamiento en la plataforma SIEX oficial.

Cuándo Exportar CUE

Para cumplir con las obligaciones legales de reporte al Ministerio
Como parte del proceso de trazabilidad obligatorio

Endpoint de Exportación

http

POST /v1/entities/siex/exportCUE?agrifarmId={agrifarm_id}

Estructura de Petición CUE

json

[
  {
    "id": "urn:ngsi-ld:AgriPhytosanitary:2941"
  },
  {
    "id": "urn:ngsi-ld:AgriPhytosanitary:2942"
  }
]

Detalles de Campos CUE

IDs de Tratamientos

id: Identificador único de cada tratamiento fitosanitario registrado
- Origen: Obtenido de la respuesta del endpoint de registro
- Uso: Especifica qué tratamientos enviar al Ministerio

Validación en SIEX

El sistema de la administración realiza las verificaciones que serán notificadas a posteriori por correo.

Respuesta de Exportación CUE

En caso de éxito, el sistema devuelve:

json

{
  "message": "Job in progress. The system will send an email once it is finished."
}

Una vez termine la subida, enviara un correo con el estado final.

Guía de Implementación Paso a Paso

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

Paso 1: Obtener Credenciales

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

Paso 2: Configuración Base

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

Paso 3: Pruebas de Integración

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

Flujo Operativo (Para cada tratamiento fitosanitario)

Paso 1: Identificar la Explotación

http

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

http

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

Objetivo: Relacionar parcelas SIGPAC con cultivos específicos

Paso 3: Registrar el Tratamiento

http

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

Objetivo: Reportar la aplicación del fitosanitaria en la plataforma

Paso 4: Verificar el Registro

http

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

Objetivo: Confirmar que el tratamiento se registró correctamente

Paso 5: Comunica a la administración

http

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:

Obtener IDs incluyendo todas las parcelas SIGPAC en una sola petición al endpoint /listidcp
Registrar una aplicación con todos los IDs obtenidos en el array idcp
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:

Realizar el flujo completo para el primer producto (herbicida)
Repetir el proceso con los mismos IDs de ubicación para el segundo producto
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

Códigos de Respuesta y Manejo de Errores

Respuestas Exitosas

Código	Significado	Descripción
200 OK	Consulta exitosa	Datos recuperados correctamente
201 Created	Registro creado	Aplicación registrada exitosamente

Errores Comunes y Soluciones

Errores de Autenticación (401)

Error	Causa Probable	Solución
Credenciales incorrectas	API Key o SID inválidos	Verificar credenciales en portal desarrollador
Token expirado	Credenciales caducadas	Renovar credenciales con soporte técnico

Errores de Validación (400)

Error	Causa Probable	Solución
Datos incompletos	Campos obligatorios faltantes	Revisar estructura de petición
Formato incorrecto	Fecha o datos mal formateados	Usar formato DD-MM-YYYY HH:mm:ss
ROPO inválido	Aplicador no autorizado	Verificar número ROPO y vigencia

Errores de Negocio (422)

Error	Causa Probable	Solución
Producto no autorizado	Fitosanitario no registrado	Usar productos del catálogo oficial
Dosis excesiva	Límites legales superados	Revisar dosis máximas autorizadas
Cultivo incompatible	Producto no apto para cultivo	Verificar compatibilidad producto-cultivo

Errores de Recurso (404)

Error	Causa Probable	Solución
Explotación no encontrada	REA incorrecto o no registrado	Verificar código REA y año
IDs inválidos	Cultivo-ubicación no configurado	Regenerar IDs con endpoint `/listidcp`

Estrategias de Manejo de Errores

1. Implementar Reintentos Inteligentes

text

- Errores 5xx: Reintentar con backoff exponencial
- Errores 429: Respetar rate limiting
- Errores 4xx: No reintentar, corregir datos

2. Validación Local Previa

text

- Verificar formato de fechas antes de enviar
- Validar existencia de códigos ROPO
- Comprobar rangos de dosis permitidas

3. Logging Detallado

text

- Registrar todas las peticiones y respuestas
- Incluir timestamps y identificadores únicos
- Mantener logs para auditorías

4. Configurar Alertas

text

- Errores recurrentes (>5 en 1 hora)
- Fallos de autenticación repetidos
- Problemas de conectividad prolongados

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

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

Actualizaciones y Mantenimiento

Notificaciones Automáticas

Cambios en la API se comunican con 30 días de antelación
Actualizaciones de catálogos de productos
Mantenimientos programados

Versionado de API

Compatibilidad hacia atrás garantizada
Migración asistida para nuevas versiones
Documentación específica por versión

Diagrama de Integración Completa

Información Técnica Adicional

Códigos de Respuesta HTTP

Código	Descripción
`200`	Operación exitosa
`201`	Recurso creado correctamente
`400`	Error en parámetros o formato de datos
`401`	No autorizado - verificar credenciales
`403`	Acceso denegado - permisos insuficientes
`404`	Recurso no encontrado
`422`	Error de validación de negocio
`429`	Límite de peticiones excedido
`500`	Error interno del servidor

Límites y Restricciones

Límites de la API

Rate Limit: Máximo 100 peticiones por minuto por cliente
Tamaño de petición: Máximo 1MB por request
Tiempo de respuesta: Timeout a los 30 segundos
Registros retroactivos: Máximo 7 días hacia atrás

Formatos de Fecha y Hora

Todos los timestamps en la API siguen el formato:

Formato estándar: DD-MM-YYYY HH:mm:ss
Zona horaria: Hora local española (CET/CEST)
Ejemplo válido: 18-06-2025 14:30:00

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.

Versión de la documentación: 2.1Última actualización: Noviembre 2025API Version: v1Formato: Cliente Final - Documentación Completa

Documentación API - Pasarela SIEX ​

Tabla de Contenidos ​

Información General de la API ​

Introducción General ​

¿Qué es la Pasarela SIEX? ​

¿Por qué usar esta solución? ​

¿Cómo funciona? ​

Arquitectura del Sistema ​

Componentes del Sistema ​

Configuración Inicial ​

Paso 1: Registro en Portal de Desarrolladores ​

Paso 2: Variables de Configuración ​

Paso 3: Configuración en CXTierra ​

Estructura de Datos y Jerarquías ​

Modelo de Entidades ​

Relaciones Entre Entidades ​

Flujo de Trabajo Completo ​

Endpoints de la API ​

Autenticación y Headers ​

1. Obtener Datos de Explotación ​

Descripción Funcional ​

Cuándo Usarlo ​

Endpoint ​

Parámetros ​

Información Devuelta para Explotación ​

Datos Básicos de la Explotación ​

Información del Propietario ​

Parcelas y Ubicaciones SIGPAC ​

Atributos Regionales ​

Respuesta Simplificada (Campos Principales) ​

Información Clave de la Respuesta ​

2. Obtener IDs de Cultivo-Ubicación ​

Descripción de IDs Cultivo-Ubicación ​

Cuándo Usar IDs Cultivo-Ubicación ​

Endpoint de IDs ​

Estructura de Petición para IDs ​

Catálogos de Referencia ​

Información de Cultivos ​

Códigos SIGPAC ​

Respuesta de IDs Cultivo-Ubicación ​

Uso de los IDs Devueltos ​

3. Registrar Aplicación Fitosanitaria ​

Descripción del Registro ​

Cuándo Registrar Tratamientos ​

Endpoint de Registro ​

Query Params Opcionales ​

Estructura de la Petición ​

Detalles de los Campos ​

Información Temporal ​

Información del Producto Fitosanitario ​

Información de Dosificación ​

Información del Aplicador ​

Ubicaciones de Aplicación ​

Validaciones Automáticas del Sistema ​

✅ Validaciones de Producto ​

✅ Validaciones de Aplicador ​

✅ Validaciones de Ubicación ​

✅ Validaciones Temporales ​

Respuesta del Sistema ​

4. Consultar Aplicaciones Registradas ​

Descripción de Consulta ​

Cuándo Consultar Aplicaciones ​

Endpoint de Consulta ​

Parámetros Opcionales ​

Respuesta del sistema ​

Información Devuelta en Consulta ​

Datos del Tratamiento ​

Datos del Aplicador ​

Metadatos del Sistema ​

5. Exportar CUE ​

Descripción de Exportación CUE ​

Cuándo Exportar CUE ​

Endpoint de Exportación ​

Estructura de Petición CUE ​

Detalles de Campos CUE ​

IDs de Tratamientos ​

Validación en SIEX ​

Respuesta de Exportación CUE ​

Guía de Implementación Paso a Paso ​

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

Documentación API - Pasarela SIEX

Tabla de Contenidos

Información General de la API

Introducción General

¿Qué es la Pasarela SIEX?

¿Por qué usar esta solución?

¿Cómo funciona?

Arquitectura del Sistema

Componentes del Sistema

Configuración Inicial

Paso 1: Registro en Portal de Desarrolladores

Paso 2: Variables de Configuración

Paso 3: Configuración en CXTierra

Estructura de Datos y Jerarquías

Modelo de Entidades

Relaciones Entre Entidades

Flujo de Trabajo Completo

Endpoints de la API

Autenticación y Headers

1. Obtener Datos de Explotación

Descripción Funcional

Cuándo Usarlo

Endpoint

Parámetros

Información Devuelta para Explotación

Datos Básicos de la Explotación

Información del Propietario

Parcelas y Ubicaciones SIGPAC

Atributos Regionales

Respuesta Simplificada (Campos Principales)

Información Clave de la Respuesta

2. Obtener IDs de Cultivo-Ubicación

Descripción de IDs Cultivo-Ubicación

Cuándo Usar IDs Cultivo-Ubicación

Endpoint de IDs

Estructura de Petición para IDs

Catálogos de Referencia

Información de Cultivos

Códigos SIGPAC

Respuesta de IDs Cultivo-Ubicación

Uso de los IDs Devueltos

3. Registrar Aplicación Fitosanitaria

Descripción del Registro

Cuándo Registrar Tratamientos

Endpoint de Registro

Query Params Opcionales

Estructura de la Petición

Detalles de los Campos

Información Temporal

Información del Producto Fitosanitario

Información de Dosificación

Información del Aplicador

Ubicaciones de Aplicación

Validaciones Automáticas del Sistema

✅ Validaciones de Producto

✅ Validaciones de Aplicador

✅ Validaciones de Ubicación

✅ Validaciones Temporales

Respuesta del Sistema

4. Consultar Aplicaciones Registradas

Descripción de Consulta

Cuándo Consultar Aplicaciones

Endpoint de Consulta

Parámetros Opcionales

Respuesta del sistema

Información Devuelta en Consulta

Datos del Tratamiento

Datos del Aplicador

Metadatos del Sistema

5. Exportar CUE

Descripción de Exportación CUE

Cuándo Exportar CUE

Endpoint de Exportación

Estructura de Petición CUE

Detalles de Campos CUE

IDs de Tratamientos

Validación en SIEX

Respuesta de Exportación CUE

Guía de Implementación Paso a Paso

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