{
  "schemaVersion": 1,
  "generatedAt": "2026-08-21T23:38:34.355Z",
  "language": "es-AR",
  "title": "Contrato público de API para Datos Chivilcoy",
  "description": "Contrato liviano para agentes IA, monitores y clientes públicos. Todas las lecturas usan GET sobre /api/index.php con action y devuelven JSON sin exponer credenciales.",
  "baseUrl": "https://datoschivilcoy.com.ar",
  "transport": {
    "method": "GET",
    "path": "/api/index.php",
    "responseContentType": "application/json",
    "authentication": "No requiere autenticación para estas acciones públicas."
  },
  "responseEnvelope": {
    "success": {
      "ok": true,
      "data": "payload de la acción solicitada"
    },
    "failure": {
      "ok": false,
      "error": "mensaje estable de error"
    }
  },
  "agentGuidance": [
    "Preferir estos endpoints sobre descargar JSON grandes cuando la consulta sea textual, paginada o de estado.",
    "Usar limit y offset cuando existan; no asumir que una respuesta trae todo el corpus.",
    "Citar sourceUrl, pdf_url, document_url, route o internal_url cuando se use un dato como evidencia.",
    "Tratar proveedores y montos como datos auditados parcialmente: revisar status, amount y amount_label antes de afirmar totales.",
    "Si un endpoint devuelve 502/503, usar los JSON documentados en ai-catalog.json como fallback operativo."
  ],
  "endpoints": [
    {
      "action": "supabase_status",
      "description": "Diagnóstico vivo de lecturas públicas Supabase, cache server-side y fuente MySQL administrativa.",
      "cache": "Sin cache de navegador; el endpoint mide estado vivo y no expone secretos.",
      "sourceModels": [
        "official_bulletin_search_index",
        "procurement_supplier_records",
        "ai_public_search_documents"
      ],
      "parameters": [
        {
          "name": "action",
          "required": true,
          "type": "literal",
          "value": "supabase_status"
        }
      ],
      "responseFields": [
        "checkedAt",
        "configured",
        "ready",
        "readModels",
        "publicCache",
        "adminMirror",
        "publicSnapshotSource",
        "syncSources",
        "checks"
      ],
      "examples": [
        {
          "url": "/api/index.php?action=supabase_status",
          "purpose": "Verificar si Supabase está listo antes de consultar modelos públicos."
        }
      ]
    },
    {
      "action": "bulletin_search",
      "description": "Búsqueda textual paginada en bloques del Boletín Oficial vía Supabase REST y proxy PHP.",
      "cache": "Cache público server-side con stale-if-error.",
      "sourceModels": [
        "official_bulletin_search_index"
      ],
      "parameters": [
        {
          "name": "action",
          "required": true,
          "type": "literal",
          "value": "bulletin_search"
        },
        {
          "name": "q",
          "required": false,
          "type": "string",
          "maxLength": 160,
          "description": "Términos de búsqueda; se ignoran tokens de menos de 2 caracteres. Si se omite, usar al menos un filtro year/type/category/quality."
        },
        {
          "name": "limit",
          "required": false,
          "type": "integer",
          "minimum": 1,
          "maximum": 120,
          "default": 120
        },
        {
          "name": "year",
          "required": false,
          "type": "integer",
          "minimum": 1900,
          "maximum": 2100
        },
        {
          "name": "type",
          "required": false,
          "type": "enum",
          "values": [
            "Boletín Oficial",
            "Decreto",
            "Ordenanza",
            "Ordenanza fiscal",
            "Ordenanza impositiva",
            "Referencia"
          ]
        },
        {
          "name": "category",
          "required": false,
          "type": "enum",
          "values": [
            "Decreto",
            "Resolución",
            "Ordenanza",
            "Ordenanza fiscal",
            "Ordenanza impositiva",
            "Página del PDF",
            "Referencia",
            "Texto"
          ],
          "description": "Categoría derivada del bloque de texto. Usar para evitar descargar índices JSON cuando se necesita filtrar por tipo de texto."
        },
        {
          "name": "quality",
          "required": false,
          "type": "enum",
          "values": [
            "reviewed",
            "auto-extracted",
            "needs-review"
          ],
          "description": "Estado de calidad derivado de review_status/text_source."
        }
      ],
      "responseFields": [
        "results[].block_id",
        "results[].body_preview",
        "results[].bulletin_id",
        "results[].published_at",
        "results[].text_category",
        "results[].quality_status",
        "results[].source_url",
        "results[].pdf_url",
        "totalCount",
        "returnedCount",
        "limit",
        "generatedAt",
        "source"
      ],
      "examples": [
        {
          "url": "/api/index.php?action=bulletin_search&q=licitacion&limit=10",
          "purpose": "Buscar licitaciones sin descargar índices JSON completos."
        },
        {
          "url": "/api/index.php?action=bulletin_search&q=decreto%20614&year=2022&type=Decreto&limit=5",
          "purpose": "Ubicar un acto normativo por número, año y tipo."
        },
        {
          "url": "/api/index.php?action=bulletin_search&q=licitacion&category=Decreto&quality=reviewed&limit=10",
          "purpose": "Filtrar por categoría y calidad desde SQL/cache sin cargar índices históricos."
        }
      ]
    },
    {
      "action": "procurement_suppliers",
      "description": "Líneas proveedor normalizadas, ranking agregado y estado de montos detectados en boletines.",
      "cache": "Cache público server-side con stale-if-error.",
      "sourceModels": [
        "procurement_supplier_records",
        "procurement_supplier_summary"
      ],
      "parameters": [
        {
          "name": "action",
          "required": true,
          "type": "literal",
          "value": "procurement_suppliers"
        },
        {
          "name": "limit",
          "required": false,
          "type": "integer",
          "minimum": 1,
          "maximum": 5000,
          "default": 5000
        },
        {
          "name": "offset",
          "required": false,
          "type": "integer",
          "minimum": 0,
          "maximum": 100000,
          "default": 0
        },
        {
          "name": "year",
          "required": false,
          "type": "integer",
          "minimum": 1900,
          "maximum": 2100
        },
        {
          "name": "supplier",
          "required": false,
          "type": "string",
          "maxLength": 180,
          "description": "supplier_key normalizado."
        }
      ],
      "responseFields": [
        "records[].supplier_name",
        "records[].amount",
        "records[].status",
        "records[].act_label",
        "records[].internal_url",
        "supplierSummary[]",
        "totalCount",
        "returnedCount",
        "complete"
      ],
      "examples": [
        {
          "url": "/api/index.php?action=procurement_suppliers&year=2023&limit=100",
          "purpose": "Revisar proveedores detectados en un año."
        }
      ]
    },
    {
      "action": "public_finance",
      "description": "Rendición de cuentas, métricas presupuestarias y tasas municipales reconstruidas desde Supabase.",
      "cache": "Cache público server-side con stale-if-error.",
      "sourceModels": [
        "accountability_reports",
        "accountability_metrics",
        "municipal_tax_rows"
      ],
      "parameters": [
        {
          "name": "action",
          "required": true,
          "type": "literal",
          "value": "public_finance"
        },
        {
          "name": "year",
          "required": false,
          "type": "integer",
          "minimum": 1900,
          "maximum": 2100
        }
      ],
      "responseFields": [
        "accountabilityReports[]",
        "taxDataset",
        "generatedAt",
        "source"
      ],
      "examples": [
        {
          "url": "/api/index.php?action=public_finance&year=2025",
          "purpose": "Leer rendición y tasas 2025 desde modelos SQL."
        }
      ]
    },
    {
      "action": "public_search",
      "description": "Búsqueda full-text de Datos Chivilcoy sobre boletines, transparencia, tasas y documentos; excluye el prototipo HCD.",
      "cache": "Cache público server-side con stale-if-error.",
      "sourceModels": [
        "search_data_portal_corpus",
        "ai_public_search_documents"
      ],
      "parameters": [
        {
          "name": "action",
          "required": true,
          "type": "literal",
          "value": "public_search"
        },
        {
          "name": "q",
          "required": false,
          "type": "string",
          "maxLength": 160
        },
        {
          "name": "limit",
          "required": false,
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "default": 20
        },
        {
          "name": "offset",
          "required": false,
          "type": "integer",
          "minimum": 0,
          "maximum": 5000,
          "default": 0
        },
        {
          "name": "year",
          "required": false,
          "type": "integer",
          "minimum": 1900,
          "maximum": 2100
        },
        {
          "name": "entityType",
          "required": false,
          "type": "enum",
          "values": [
            "boletin_bloque",
            "documento_publico",
            "rendicion_metrica",
            "tasa_municipal"
          ]
        }
      ],
      "responseFields": [
        "results[].entityType",
        "results[].id",
        "results[].title",
        "results[].summary",
        "results[].route",
        "results[].sourceUrl",
        "results[].metadata",
        "hasMore"
      ],
      "examples": [
        {
          "url": "/api/index.php?action=public_search&q=deuda%20flotante&limit=5",
          "purpose": "Buscar en el corpus público para responder preguntas de agentes IA."
        },
        {
          "url": "/api/index.php?action=public_search&entityType=boletin_bloque&year=2025&limit=20",
          "purpose": "Listar resultados por tipo y año con paginación."
        }
      ]
    }
  ],
  "fallbackFiles": [
    "/data/ai-catalog.json",
    "/data/data-visibility-inventory.json",
    "/data/supabase-public-schema.json",
    "/data/boletines/landing-summary.json",
    "/data/transparencia/rendicion-2025.json",
    "/data/transparencia/personal-municipal-2018.json",
    "/data/transparencia/personal-municipal-2018-personas.csv",
    "/data/transparencia/personal-municipal-2018-asignaciones.csv",
    "/data/transparencia/personal-municipal-2018-sibom-cruce.json",
    "/data/transparencia/personal-municipal-2018-sibom-cruce.csv",
    "/data/transparencia/personal-municipal-2018-sibom-anexos-cruce.csv",
    "/data/transparencia/personal-municipal-2018-sibom-revision.json",
    "/data/transparencia/personal-municipal-2018-sibom-revision.csv",
    "/data/organigrama/personas-cruce-estado.json",
    "/data/boletines/sibom-annex-records.json",
    "/data/boletines/sibom-annex-records.csv",
    "/data/tasas/tasas-2025.json"
  ]
}