Documentación para desarrolladores

La API de Segesio ERP te deja leer y escribir los datos de tu cuenta — actividades, gastos, insumos, cosechas, y el resto de los módulos operativos — desde tus propios sistemas, sin pasar por la interfaz web.

No es una API espejo ni un mock: una API key con permiso de escritura llama exactamente a los mismos endpoints que usa la aplicación web, autenticada con la identidad de un usuario real de tu cuenta. Es una funcionalidad del plan Enterprise.

Cada request lleva la API key en el header X-API-Key. No hay login ni token que expire en minutos — la key es válida hasta la fecha de vencimiento que se le asignó.

La key completa sólo se muestra una vez, en el momento de crearla. Guárdala en un lugar seguro (un gestor de secretos, no un repositorio de código) — si la pierdes, hay que generar una nueva.

Un usuario con rol de administrador puede crear keys desde Configuración → API Keys, dentro de la aplicación.

1. Elige un nombre descriptivo (por ejemplo, el sistema que va a usarla).
2. Selecciona los scopes que necesita — nunca marques más de lo que esa integración realmente va a usar.
3. Si algún scope es de escritura, elige qué usuario de tu equipo representa esa key: las escrituras corren con la identidad y los permisos reales de esa persona.
4. Define un vencimiento (hay un valor por defecto si no eliges uno) y confirma.

La key completa aparece una única vez en pantalla, justo después de crearla. Copiala antes de cerrar esa vista.

Cada scope sigue el mismo formato que usa el resto del sistema: módulo:acción. Una key nunca puede hacer más de lo que el usuario al que está atada podría hacer manualmente en la interfaz.

La acción eliminar nunca está disponible para ninguna key, en ningún módulo — para borrar algo hay que hacerlo desde la interfaz normal.

El acceso de lectura viene incluido en el plan Enterprise. El acceso de escritura es una habilitación aparte, activada por nuestro equipo a pedido — escríbenos (ver Soporte, más abajo) para activarlo en tu cuenta.

Todos los endpoints usan el mismo prefijo de la API real de Segesio ERP. Un ejemplo, crear una actividad:

Cuando la key tiene un scope de escritura, la actividad creada queda atribuida al usuario real al que la key está atada — el mismo dato que quedaría si esa persona la hubiera cargado desde la web.

Las respuestas exitosas devuelven el recurso creado o solicitado en JSON. Un error — permiso faltante, dato inválido, key vencida — devuelve un código HTTP acorde y un cuerpo con este formato:

Este formato es el que usa el framework por defecto en la mayoría de los endpoints. No está estandarizado al 100% en todos los casos todavía — decimos esto para que tu integración no dependa de una estructura exacta más allá de statusCode/message.

• Rate limiting por key (no por dirección IP): una key comparte los mismos límites que el tráfico normal de la aplicación, agrupados por la propia key en vez de por IP.
• Toda key tiene vencimiento obligatorio — 90 días por defecto si tiene algún scope de escritura, 180 días si es sólo lectura. Se puede elegir un valor distinto al crearla.
• Hasta 30 scopes por key.

Si solo necesitas leer un puñado de datos — fincas, lotes, NDVI, cosechas, clima — sin escribir nada, existe una API más simple y estable pensada para eso, con estos scopes:

• fincas:read
• lotes:read
• ndvi:read
• harvest:read
• weather:read

Es un contrato más chico y estable, útil para integraciones simples. No reemplaza al catálogo completo de arriba, que sí permite escribir.

• La mayoría de los endpoints de listado devuelven el resultado completo, sin paginación — para volúmenes grandes, filtra por los parámetros que cada endpoint acepta.
• No hay webhooks salientes todavía: tu integración tiene que consultar (poll), no hay forma de que Segesio te avise de un cambio.
• El formato de error no está estandarizado al 100% en todos los endpoints — ver la nota en Formato de respuesta y errores.
• No hay rotación de keys sin recrearlas: para rotar una key hay que crear una nueva y revocar la anterior.

¿Necesitas que habilitemos escritura en tu cuenta, o tienes una pregunta puntual sobre algún endpoint? Escríbenos.