Saltar al contenido
Agro MarketProductores de Caldas
Ingresar Registrarme
Inicio Productores Centro de información Logística Verificar certificado
Ingresar Registrarme como productor Registrarme como operador

Interoperabilidad · versión 1

Servicios web de Agro Market

API REST de solo lectura para que los sistemas de la Gobernación, las alcaldías y los operadores consulten la oferta agropecuaria, las convocatorias y la validez de los documentos emitidos por la plataforma.

Acceso

  1. La entidad solicita el acceso a la Gobernación de Caldas indicando el sistema que se conectará y la información que necesita.
  2. El administrador crea el cliente en el panel (Administración → Servicios web) y entrega una llave que empieza por agro_.
  3. Cada petición envía la llave en la cabecera Authorization: Bearer <llave> (o X-Api-Key: <llave>). Nunca la ponga en la URL.
curl -H "Authorization: Bearer agro_…" https://agro.pgcsas.com/api/v1/productores?municipio=1&por_pagina=50

Convenciones

  • Dirección base: https://agro.pgcsas.com/api/v1. GET /api/v1 muestra el nombre del cliente y los servicios habilitados para su llave.
  • Formato: JSON en UTF-8 (o XML con Accept: application/xml). Fechas en formato ISO AAAA-MM-DD, hora de Colombia; valores en pesos colombianos.
  • Listas paginadas: ?pagina=1&por_pagina=20 (máximo 100). La respuesta trae datos y paginacion (total, pagina, por_pagina, paginas), y las cabeceras X-Total-Count y X-Page-Count.
  • Límite de uso: cada llave tiene un número de peticiones por minuto (cabeceras X-Rate-Limit-*); al superarlo la respuesta es 429.
  • Errores: 401 llave ausente o inválida, 403 información no habilitada para la llave, 404 recurso inexistente, 429 límite superado. El cuerpo trae name, message y status.
  • Privacidad: los servicios solo entregan información pública del catálogo. No exponen teléfonos, correos, documentos ni la ubicación exacta de las fincas (Ley 1581 de 2012).

Catálogo

alcance: catalogo
ServicioQué devuelveFiltros
GET /productores Productores aprobados. municipio (id), tipo (pequeno, mediano, grande, asociacion), categoria (id), certificado=1 (solo con certificado vigente), q (texto)
GET /productores/{id} Un productor con su descripción y sus productos publicados. —
GET /productos Productos publicados y aprobados, con su productor. categoria (id), municipio (id), productor (id), q (texto)
GET /municipios Municipios con su código DANE y coordenadas. —
GET /categorias Categorías de producto. —

Convocatorias

alcance: convocatorias
ServicioQué devuelveFiltros
GET /convocatorias Necesidades de compra publicadas (por defecto, solo las abiertas). estado=todas (incluye cerradas), municipio (id), categoria (id)
GET /convocatorias/{id} Detalle de una convocatoria. —

Verificación de documentos

alcance: verificacion
ServicioQué devuelveFiltros
GET /verificacion/{codigo} Valida un Certificado de Confianza (código de 32 caracteres) o un paz y salvo (PYS-…). —

Compras públicas

alcance: compras
ServicioQué devuelveFiltros
GET /compras Procesos de compra finalizados con paz y salvo: producto, cantidad, valor pagado, productor y entidad compradora. desde, hasta (AAAA-MM-DD), anio, municipio (id), categoria (id)
GET /compras/resumen Totales de compras a productores locales por municipio y por categoría. anio, desde, hasta

Ejemplo de respuesta

GET /api/v1/verificacion/PYS-10121110D8
{
  "datos": {
    "tipo": "paz_y_salvo",
    "codigo": "PYS-10121110D8",
    "valido": true,
    "numero_proceso": "PC-2026-00001",
    "fecha": "2026-10-12",
    "producto": "Mora de Castilla",
    "productor": { "nombre": "…", "municipio": { "id": 1, "nombre": "Manizales", "codigo_dane": "17001" } },
    "entidad_compradora": "…"
  }
}