{
  "openapi": "3.1.0",
  "info": {
    "title": "API de Proveedores Ecuador",
    "version": "1.0.0",
    "description": "API pública de proveedoresecuador.com: procesos de contratación pública publicados en SERCOP en los últimos días, detalle actualizado de un proceso y solicitudes de cotización, listados y alertas. Los datos provienen de fuentes abiertas oficiales (SERCOP/OCDS, SRI, Superintendencia de Compañías).",
    "contact": { "name": "Proveedores Ecuador", "email": "contacto@proveedoresecuador.com", "url": "https://proveedoresecuador.com/desarrolladores/" },
    "termsOfService": "https://proveedoresecuador.com/legal/terminos/"
  },
  "servers": [{ "url": "https://proveedoresecuador.com" }],
  "externalDocs": { "description": "Documentación", "url": "https://proveedoresecuador.com/desarrolladores/" },
  "tags": [
    { "name": "Procesos", "description": "Procesos de contratación pública (SERCOP)" },
    { "name": "Solicitudes", "description": "Formularios del portal (requieren consentimiento de tratamiento de datos)" },
    { "name": "Estado", "description": "Salud del servicio" }
  ],
  "paths": {
    "/api/procesos": {
      "get": {
        "tags": ["Procesos"],
        "operationId": "listarProcesos",
        "summary": "Procesos nuevos publicados en SERCOP",
        "description": "Procesos publicados en los últimos días (máximo 14), del más reciente al más antiguo. Se actualiza cada 3 horas; respuesta en caché 30 minutos.",
        "parameters": [
          { "name": "q", "in": "query", "description": "Palabras clave (todas deben aparecer en objeto, entidad, lugar o código)", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "provincia", "in": "query", "description": "Provincia, p. ej. Pichincha", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "tipo", "in": "query", "description": "Tipo de proceso (coincidencia parcial), p. ej. Subasta Inversa", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "entidad", "in": "query", "description": "Nombre de la entidad contratante", "schema": { "type": "string", "maxLength": 200 } },
          { "name": "dias", "in": "query", "description": "Días hacia atrás", "schema": { "type": "integer", "minimum": 1, "maximum": 14, "default": 7 } },
          { "name": "limite", "in": "query", "description": "Máximo de procesos devueltos", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 40 } }
        ],
        "responses": {
          "200": {
            "description": "Procesos encontrados",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListaProcesos" } } }
          }
        }
      }
    },
    "/api/proceso": {
      "get": {
        "tags": ["Procesos"],
        "operationId": "verProceso",
        "summary": "Detalle actualizado de un proceso",
        "description": "Consulta el registro OCDS del proceso en SERCOP (caché de 7 días).",
        "parameters": [
          { "name": "ocid", "in": "query", "required": true, "description": "Identificador OCDS, p. ej. ocds-5wno2w-LCC-GADMC-L-2024-06-38760", "schema": { "type": "string", "pattern": "^ocds-[a-z0-9]+-[A-Za-z0-9._-]{3,120}$" } }
        ],
        "responses": {
          "200": { "description": "Detalle del proceso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proceso" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/cotizacion": {
      "post": {
        "tags": ["Solicitudes"],
        "operationId": "solicitarCotizacion",
        "summary": "Solicitar cotización de un producto o servicio",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Solicitud" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/compradores": {
      "post": {
        "tags": ["Solicitudes"],
        "operationId": "solicitarListadoCompradores",
        "summary": "Solicitar el listado de entidades compradoras de un producto",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Solicitud" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/contratante": {
      "post": {
        "tags": ["Solicitudes"],
        "operationId": "solicitarListadoContratante",
        "summary": "Solicitar el listado completo de una entidad contratante",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Solicitud" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/alertas": {
      "post": {
        "tags": ["Solicitudes"],
        "operationId": "suscribirAlertas",
        "summary": "Suscribirse a alertas de procesos nuevos",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Solicitud" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/derechos": {
      "post": {
        "tags": ["Solicitudes"],
        "operationId": "solicitarDerechos",
        "summary": "Ejercer derechos sobre datos personales (LOPDP) o pedir corrección/exclusión de una empresa",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["tipo", "nombre", "email", "detalle"],
            "properties": {
              "tipo": { "type": "string", "enum": ["acceso", "rectificacion", "eliminacion", "oposicion", "portabilidad", "correccion_empresa", "exclusion_empresa"] },
              "nombre": { "type": "string", "maxLength": 120 },
              "identificacion": { "type": "string", "maxLength": 20, "description": "Cédula o RUC" },
              "email": { "type": "string", "format": "email", "maxLength": 160 },
              "detalle": { "type": "string", "maxLength": 3000 }
            }
          } } }
        },
        "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/salud": {
      "get": {
        "tags": ["Estado"],
        "operationId": "salud",
        "summary": "Estado del servicio",
        "responses": {
          "200": { "description": "Servicio disponible", "content": { "application/health+json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pass"] } } } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ListaProcesos": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "actualizado": { "type": ["string", "null"], "description": "Última actualización desde SERCOP" },
          "total": { "type": "integer" },
          "procesos": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "fecha": { "type": "string", "description": "Fecha de publicación (ISO 8601)" },
                "codigo": { "type": "string" },
                "tipo": { "type": "string" },
                "objeto": { "type": ["string", "null"] },
                "presupuesto": { "type": ["number", "null"], "description": "USD" },
                "lugar": { "type": "string" },
                "entidad": { "type": "string" },
                "ruta": { "type": ["string", "null"], "description": "Ficha de la entidad en el portal" }
              }
            }
          }
        }
      },
      "Proceso": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "descripcion": { "type": ["string", "null"] },
          "estado": { "type": ["string", "null"] },
          "metodo": { "type": ["string", "null"] },
          "oferentes": { "type": ["integer", "null"] },
          "presupuesto": { "type": ["number", "null"] },
          "ofertas": { "type": ["object", "null"], "properties": { "inicio": { "type": ["string", "null"] }, "fin": { "type": ["string", "null"] } } },
          "contrato": { "type": ["object", "null"] },
          "documentos": { "type": "integer" }
        }
      },
      "Solicitud": {
        "type": "object",
        "required": ["producto", "nombre", "email", "consentimiento"],
        "properties": {
          "producto": { "type": "string", "maxLength": 200, "description": "Producto, servicio o entidad de interés" },
          "producto_slug": { "type": "string", "maxLength": 120 },
          "cantidad": { "type": "string", "maxLength": 120 },
          "ciudad": { "type": "string", "maxLength": 120 },
          "provincia_pagina": { "type": "string", "maxLength": 60 },
          "detalle": { "type": "string", "maxLength": 3000 },
          "nombre": { "type": "string", "maxLength": 120 },
          "empresa": { "type": "string", "maxLength": 160 },
          "ruc": { "type": "string", "maxLength": 13 },
          "email": { "type": "string", "format": "email", "maxLength": 160 },
          "telefono": { "type": "string", "maxLength": 40 },
          "pagina": { "type": "string", "maxLength": 400 },
          "consentimiento": { "type": "boolean", "const": true, "description": "Aceptación del tratamiento de datos (LOPDP)" }
        }
      }
    },
    "responses": {
      "Ok": { "description": "Solicitud registrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } },
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }
    }
  }
}