{
  "openapi": "3.1.0",
  "info": {
    "title": "ForgeNEX Agent API",
    "version": "1.1.0",
    "description": "API pública para agentes IA y sistemas externos que necesiten interactuar con los servicios de ForgeNEX. Permite solicitar consultoría, diagnósticos y consultar el catálogo de servicios.",
    "contact": {
      "name": "ForgeNEX",
      "email": "info@forgenex.com",
      "url": "https://www.forgenex.com"
    }
  },
  "servers": [
    {
      "url": "https://www.forgenex.com",
      "description": "Servidor de producción"
    }
  ],
  "security": [
    {
      "oauth2": []
    }
  ],
  "paths": {
    "/api/consultoria": {
      "post": {
        "operationId": "solicitarConsultoria",
        "summary": "Solicitar consultoría TI o IA",
        "description": "Envía una solicitud de consultoría tecnológica (IT, IA, Cloud, CRM, Ciberseguridad). El equipo de ForgeNEX contactará en un plazo de 24h.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsultoriaRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Solicitud registrada correctamente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsultoriaResponse"
                }
              }
            }
          },
          "400": {
            "description": "Parámetros incorrectos o faltantes"
          },
          "401": {
            "description": "No autorizado — token inválido o expirado"
          }
        }
      }
    },
    "/api/diagnostico": {
      "post": {
        "operationId": "solicitarDiagnostico",
        "summary": "Solicitar diagnóstico tecnológico",
        "description": "Solicita un diagnóstico inicial de la infraestructura IT de la empresa. Devuelve un ID de seguimiento y el tiempo estimado de respuesta.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiagnosticoRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnóstico solicitado correctamente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticoResponse"
                }
              }
            }
          },
          "401": {
            "description": "No autorizado"
          }
        }
      }
    },
    "/api/servicios": {
      "get": {
        "operationId": "listarServicios",
        "summary": "Listar catálogo de servicios",
        "description": "Devuelve el catálogo completo de servicios de ForgeNEX con descripción, vertical y URL de detalle.",
        "security": [],
        "responses": {
          "200": {
            "description": "Catálogo de servicios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Servicio"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 Client Credentials. Ver auth.md para obtener credenciales.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://www.forgenex.com/api/auth/token",
            "scopes": {
              "consultoria:read": "Consultar disponibilidad y catálogo",
              "consultoria:write": "Enviar solicitudes de consultoría",
              "diagnostico:read": "Solicitar diagnóstico tecnológico",
              "crm:write": "Interactuar con el CRM NEXgestión"
            }
          }
        }
      }
    },
    "schemas": {
      "ConsultoriaRequest": {
        "type": "object",
        "required": ["nombre", "email", "area"],
        "properties": {
          "nombre": {
            "type": "string",
            "description": "Nombre del contacto o empresa"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email de contacto"
          },
          "area": {
            "type": "string",
            "enum": ["ia", "cloud", "desarrollo", "ciberseguridad", "crm", "soporte", "consultoria"],
            "description": "Área de consultoría solicitada"
          },
          "mensaje": {
            "type": "string",
            "description": "Descripción del proyecto o necesidad"
          },
          "ciudad": {
            "type": "string",
            "description": "Ciudad de la empresa (opcional)"
          }
        }
      },
      "ConsultoriaResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID de la solicitud generada"
          },
          "estado": {
            "type": "string",
            "example": "recibida"
          },
          "tiempo_respuesta": {
            "type": "string",
            "example": "24h"
          }
        }
      },
      "DiagnosticoRequest": {
        "type": "object",
        "required": ["empresa", "email"],
        "properties": {
          "empresa": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "num_empleados": {
            "type": "integer"
          },
          "descripcion": {
            "type": "string",
            "description": "Resumen de la situación tecnológica actual"
          }
        }
      },
      "DiagnosticoResponse": {
        "type": "object",
        "properties": {
          "id_diagnostico": {
            "type": "string"
          },
          "estado": {
            "type": "string",
            "example": "en_proceso"
          },
          "tiempo_estimado": {
            "type": "string",
            "example": "48h"
          }
        }
      },
      "Servicio": {
        "type": "object",
        "properties": {
          "nombre": {
            "type": "string"
          },
          "vertical": {
            "type": "string"
          },
          "descripcion": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}