{
  "openapi": "3.1.0",
  "info": {
    "title": "GuaranIA Public API & Agent Interface",
    "version": "1.0.0",
    "description": "Public API specification for GuaranIA. Provides endpoints for discovering AI services, company credentials, automation feasibility assessment, and agent interaction in Paraguay and Latin America.",
    "contact": {
      "name": "GuaranIA Technical Support",
      "email": "contacto@guarania.com.py",
      "url": "https://guarania.com.py/docs"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://guarania.com.py",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "getApiHealth",
        "summary": "Check API health and capabilities",
        "description": "Returns current operational status, active version, timestamp, and AI agent integration capabilities.",
        "responses": {
          "200": {
            "description": "API is operational and healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/services": {
      "get": {
        "operationId": "listServices",
        "summary": "List AI and automation services",
        "description": "Retrieves the catalog of GuaranIA services including AI consulting, custom LLM agents, RPA automation, web development, and data analytics.",
        "responses": {
          "200": {
            "description": "Catalog of available services",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicesListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/organization": {
      "get": {
        "operationId": "getOrganizationInfo",
        "summary": "Get verified organization data",
        "description": "Returns verified company profile, address in Asunción Paraguay, contact points, tax ID info, and official links for AI trust verification.",
        "responses": {
          "200": {
            "description": "Verified organization metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contact": {
      "post": {
        "operationId": "submitContactInquiry",
        "summary": "Submit a business inquiry or lead",
        "description": "Allows AI agents and users to submit a project inquiry or consultation request directly to GuaranIA engineers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactInquiryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry accepted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactInquiryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/assessment": {
      "post": {
        "operationId": "evaluateAutomationFeasibility",
        "summary": "Evaluate process automation feasibility",
        "description": "Analyzes a business workflow description and determines feasibility for AI agent or RPA automation, returning estimated complexity and ROI tier.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssessmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Automation feasibility report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssessmentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": ["status", "version", "timestamp", "environment", "agent_friendly"],
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "version": { "type": "string", "example": "1.0.0" },
          "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-16T12:00:00Z" },
          "environment": { "type": "string", "example": "production" },
          "agent_friendly": { "type": "boolean", "example": true },
          "mcp_enabled": { "type": "boolean", "example": true }
        }
      },
      "ServiceItem": {
        "type": "object",
        "required": ["id", "name", "category", "description", "capabilities", "tier", "target_market"],
        "properties": {
          "id": { "type": "string", "example": "custom-ai-agents" },
          "name": { "type": "string", "example": "Agentes de Inteligencia Artificial a Medida" },
          "category": { "type": "string", "example": "AI Development" },
          "description": { "type": "string", "example": "Modelos LLM autónomos entrenados con datos privados de la empresa y conectores de negocio." },
          "capabilities": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["WhatsApp Business integration", "ERP/CRM connectors", "Private RAG pipelines"]
          },
          "tier": { "type": "string", "enum": ["Starter", "Professional", "Enterprise"], "example": "Professional" },
          "target_market": { "type": "string", "example": "Empresas en Paraguay y Latinoamérica" }
        }
      },
      "ServicesListResponse": {
        "type": "object",
        "required": ["count", "services"],
        "properties": {
          "count": { "type": "integer", "example": 5 },
          "services": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ServiceItem" }
          }
        }
      },
      "OrganizationResponse": {
        "type": "object",
        "required": ["name", "legalName", "url", "email", "phone", "address", "country"],
        "properties": {
          "name": { "type": "string", "example": "GuaranIA" },
          "legalName": { "type": "string", "example": "GuaranIA" },
          "url": { "type": "string", "format": "uri", "example": "https://guarania.com.py" },
          "email": { "type": "string", "format": "email", "example": "contacto@guarania.com.py" },
          "phone": { "type": "string", "example": "+595982672619" },
          "address": {
            "type": "object",
            "required": ["streetAddress", "locality", "country"],
            "properties": {
              "streetAddress": { "type": "string", "example": "Avda. Santa Teresa y Aviadores del Chaco" },
              "locality": { "type": "string", "example": "Asunción" },
              "country": { "type": "string", "example": "PY" }
            }
          },
          "country": { "type": "string", "example": "Paraguay" },
          "established": { "type": "string", "example": "2024" },
          "verified": { "type": "boolean", "example": true }
        }
      },
      "ContactInquiryRequest": {
        "type": "object",
        "required": ["name", "email", "message"],
        "properties": {
          "name": { "type": "string", "description": "Full name or representative", "example": "Carlos Benítez" },
          "email": { "type": "string", "format": "email", "description": "Corporate email address", "example": "carlos@empresa.com.py" },
          "company": { "type": "string", "description": "Company name", "example": "Distribuidora del Este" },
          "service_interest": {
            "type": "string",
            "enum": ["ai-agents", "rpa-automation", "web-development", "saas-products", "data-analytics", "consulting"],
            "example": "ai-agents"
          },
          "message": { "type": "string", "description": "Description of business challenge or requirements", "example": "Necesitamos automatizar la carga de comprobantes tributarios al ERP." }
        }
      },
      "ContactInquiryResponse": {
        "type": "object",
        "required": ["success", "message", "inquiry_id", "next_steps"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "Consulta recibida. Un ingeniero de GuaranIA revisará los requerimientos." },
          "inquiry_id": { "type": "string", "example": "inq_2026_0916_abc" },
          "next_steps": { "type": "string", "example": "Respuesta técnica en menos de 24 horas hábiles a su correo corporativo." }
        }
      },
      "AssessmentRequest": {
        "type": "object",
        "required": ["process_description", "current_tools", "monthly_volume"],
        "properties": {
          "process_description": { "type": "string", "description": "Step-by-step description of the operational task", "example": "Copia de datos de facturas PDF recibidas por correo hacia SAP." },
          "current_tools": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["SAP ERP", "Microsoft Outlook", "Excel"]
          },
          "monthly_volume": { "type": "integer", "description": "Number of executions per month", "example": 1500 },
          "human_hours_per_month": { "type": "number", "description": "Hours currently spent by team", "example": 80 }
        }
      },
      "AssessmentResponse": {
        "type": "object",
        "required": ["feasibility_score", "recommended_technology", "estimated_savings_percentage", "complexity_level"],
        "properties": {
          "feasibility_score": { "type": "number", "minimum": 0, "maximum": 100, "example": 94 },
          "recommended_technology": { "type": "string", "example": "RPA con extracción LLM OCR y conector API SAP" },
          "estimated_savings_percentage": { "type": "number", "example": 85 },
          "complexity_level": { "type": "string", "enum": ["Low", "Medium", "High"], "example": "Medium" },
          "guidance": { "type": "string", "example": "Proceso altamente repetitivo con reglas estructuradas ideal para automatización continua." }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "status"],
            "properties": {
              "code": { "type": "string", "example": "BAD_REQUEST" },
              "message": { "type": "string", "example": "Missing required field: email" },
              "status": { "type": "integer", "example": 400 },
              "resolution": { "type": "string", "example": "Provide a valid email address." },
              "docs_url": { "type": "string", "example": "https://guarania.com.py/docs" }
            }
          }
        }
      }
    }
  }
}