API de integración de Agro25 Panamá

Esta API permite a una entidad del Estado (o a otro sistema autorizado) consultar datos agregados de la plataforma y enviarle información oficial: precios de referencia, validación de registros sanitarios y avisos. El acceso es por llave; solicítala al administrador de Agro25 Panamá.

Autenticación

Cada solicitud lleva la llave en el encabezado. Las dos formas son equivalentes:

Authorization: Bearer agri_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
// o
X-Api-Key: agri_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La llave tiene uno o más permisos (scopes). Una solicitud sin el permiso necesario recibe 403. Límite: 60 solicitudes por minuto por llave (429 si se supera).

Permisos (scopes)

PRICES_READ: Leer precios y brecha de precios
SUPPLY_READ: Leer oferta, demanda y siembra prevista
SANITARY_READ: Leer estado de registros sanitarios y certificados
OFFICIAL_WRITE: Enviar datos oficiales (precio de referencia, validación sanitaria, avisos)
FINANCING_READ: Ver solicitudes de adelanto de cosecha y su elegibilidad
FINANCING_WRITE: Aprobar, rechazar y desembolsar adelantos de cosecha

Consultar datos (GET)

Precios recientes — requiere `PRICES_READ`

GET https://agri25.vercel.app/api/v1/partner/precios?days=30

{
  "generatedAt": "2026-01-01T00:00:00.000Z",
  "days": 30,
  "data": [
    { "producto": "Tomate", "producto_id": "clx...", "unidad": "quintal", "mercado": "Volcán",
      "precio_min": 12.5, "precio_prom": 15.0, "precio_max": 18.0, "registros": 42, "ultimo_registro": "2026-01-01" }
  ]
}

Oferta, demanda y siembra prevista — requiere `SUPPLY_READ`

GET https://agri25.vercel.app/api/v1/partner/oferta-demanda

{
  "oferta_demanda": [{ "producto": "Tomate", "categoria": "Hortalizas", "unidad": "quintal", "oferta": 500, "demanda": 420, "relacion": 1.19, "situacion": "EXCEDENTE" }],
  "siembra_prevista": [{ "mes": "2026-03", "producto": "Tomate", "unidad": "quintal", "cantidad_prevista": 1200, "productores": 8 }]
}

Una cifra construida con menos de 3 productores se omite (productores: null), para no identificar a nadie.

Estado de un registro sanitario — requiere `SANITARY_READ`

GET https://agri25.vercel.app/api/v1/partner/sanitario?numero=RS-12345

{ "encontrado": true, "tipo": "SANITARY_REGISTRY", "estado": "ACTIVE", "emitido": "2025-01-10", "vence": "2027-01-10", "confirmado_por_socio": false }

Enviar datos oficiales (POST) — requiere `OFFICIAL_WRITE`

POST https://agri25.vercel.app/api/v1/partner/oficial
Content-Type: application/json

{ "kind": "PRICE_REFERENCE", "productId": "clx...", "price": 14.5, "unit": "quintal", "recordedDate": "2026-01-01" }

kind puede ser:

PRICE_REFERENCE: productId, price, unit, recordedDate (opcional). Se muestra junto a los precios de la red.
SANITARY_REGISTRY: number (el número de registro tal como lo tiene el productor) y valid (booleano). Si existe un certificado con ese número, se marca como confirmado por el socio o se retira si valid: false.
SUPPLY_ALERT: cualquier estructura; queda registrada para que el administrador la revise (por ejemplo, una alerta sanitaria de una zona o producto).

{ "id": "clx...", "aplicado": true, "nota": "Precio de referencia guardado." }

Errores

401 llave inválida o desactivada · 403 sin el permiso necesario · 429 demasiadas solicitudes · 400 parámetros faltantes o inválidos. El cuerpo siempre trae { "error": "..." }.

Datos abiertos, sin llave

Los mismos indicadores agregados también están disponibles sin autenticación, en https://agri25.vercel.app/api/open-data/{precios|brecha|oferta-demanda|siembra|licitaciones} (JSON o ?format=csv).