{
  "openapi": "3.1.0",
  "info": {
    "title": "AvluoInm24 Valuation Request API",
    "version": "1.0.0",
    "description": "API pública detectada en el formulario y backend para registrar solicitudes de valuación inmobiliaria estimada. Este servicio no genera avalúos oficiales ni documentos con validez bancaria, notarial, fiscal, judicial o administrativa."
  },
  "servers": [
    {
      "url": "https://api.avaluoinmueble.com.mx",
      "description": "Servidor real usado por el formulario público"
    }
  ],
  "paths": {
    "/api/avaluo/solicitar": {
      "post": {
        "operationId": "createValuationRequest",
        "summary": "Registrar solicitud de valuación inmobiliaria estimada",
        "description": "Registra los datos de contacto y del inmueble para solicitar una valuación inmobiliaria estimada. La ruta fue detectada en el formulario público y en el backend del proyecto.",
        "tags": [
          "Valuation Requests"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValuationRequest"
              },
              "examples": {
                "cdmxApartment": {
                  "summary": "Departamento en CDMX",
                  "value": {
                    "nombre_cliente": "Juan Pérez García",
                    "correo_cliente": "juan@example.com",
                    "telefono_cliente": "+52 55 1234 5678",
                    "estado": "CIUDAD DE MEXICO",
                    "alcaldia": "Benito Juárez",
                    "colonia": "Del Valle",
                    "codigoPostal": "03100",
                    "tipo_inmueble": "departamento",
                    "superficie_terreno_m2": "85",
                    "superficie_construida_m2": "85",
                    "recamaras": "2",
                    "banos": "2",
                    "estacionamientos": "1",
                    "antiguedad_anos": "10",
                    "estado_conservacion": "Bueno",
                    "usoSuelo": "Habitacional",
                    "precio_deseado_mxn": "3500000",
                    "amenidades": "elevador,seguridad_24h"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Solicitud recibida exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValuationSuccessResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "success": true,
                      "solicitudId": 12345,
                      "message": "Solicitud recibida exitosamente",
                      "detalles": {
                        "ubicacion": "Del Valle, Benito Juárez, CDMX",
                        "tipo_inmueble": "departamento",
                        "superficie": "85"
                      },
                      "nota": "Recibirás tu estudio de mercado por correo electrónico en las próximas 24 horas.",
                      "processingTime": "350ms"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos o incompletos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "validationError": {
                    "value": {
                      "error": "Datos inválidos",
                      "detalles": [
                        "correo_cliente: Email inválido"
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error interno del servidor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "serverError": {
                    "value": {
                      "error": "Error interno del servidor",
                      "message": "No se pudo procesar tu solicitud. Por favor intenta nuevamente."
                    }
                  }
                }
              }
            }
          }
        },
        "x-avluoinm24": {
          "status": "active",
          "endpoint_source": [
            "01_WEB_SITE/index.html:1668",
            "01_WEB_SITE/Backend/server.js:918"
          ],
          "official_appraisal": false,
          "legal_validity": false
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NumericFormValue": {
        "oneOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "pattern": "^[0-9]+(\\.[0-9]+)?$"
          }
        ]
      },
      "ValuationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "nombre_cliente",
          "correo_cliente",
          "estado",
          "colonia",
          "tipo_inmueble",
          "superficie_terreno_m2",
          "superficie_construida_m2",
          "recamaras",
          "banos",
          "precio_deseado_mxn"
        ],
        "properties": {
          "nombre_cliente": {
            "type": "string",
            "minLength": 3,
            "maxLength": 100,
            "description": "Nombre completo del solicitante."
          },
          "correo_cliente": {
            "type": "string",
            "format": "email",
            "description": "Correo electrónico donde se enviará seguimiento."
          },
          "telefono_cliente": {
            "type": "string",
            "minLength": 7,
            "maxLength": 20,
            "description": "Teléfono de contacto opcional."
          },
          "estado": {
            "type": "string",
            "enum": [
              "CIUDAD DE MEXICO",
              "ESTADO DE MEXICO",
              "MORELOS",
              "QUINTANA ROO"
            ],
            "description": "Entidad federativa enviada por el formulario público."
          },
          "alcaldia": {
            "type": "string",
            "maxLength": 120,
            "description": "Alcaldía requerida para inmuebles en CIUDAD DE MEXICO."
          },
          "municipio": {
            "type": "string",
            "maxLength": 120,
            "description": "Municipio requerido para ESTADO DE MEXICO y usado por el formulario para MORELOS y QUINTANA ROO."
          },
          "colonia": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "Colonia donde se ubica el inmueble."
          },
          "codigoPostal": {
            "type": "string",
            "pattern": "^[0-9]{5}$",
            "description": "Código postal opcional capturado por el formulario."
          },
          "tipo_inmueble": {
            "type": "string",
            "enum": [
              "casa",
              "departamento",
              "terreno",
              "local",
              "oficina"
            ],
            "description": "Tipo de inmueble aceptado por la validación del backend. Nota: el formulario visible muestra 'local comercial', que debe normalizarse a 'local' antes de llamar directamente a la API."
          },
          "superficie_terreno_m2": {
            "$ref": "#/components/schemas/NumericFormValue",
            "description": "Superficie total aproximada en metros cuadrados."
          },
          "superficie_construida_m2": {
            "$ref": "#/components/schemas/NumericFormValue",
            "description": "Superficie construida en metros cuadrados. El backend valida rango aproximado de 10 a 10000."
          },
          "superficie_construida": {
            "$ref": "#/components/schemas/NumericFormValue",
            "description": "Campo alternativo compatible con backend para superficie construida."
          },
          "recamaras": {
            "type": "string",
            "description": "Número de recámaras capturado por el formulario."
          },
          "banos": {
            "type": "string",
            "description": "Número de baños capturado por el formulario."
          },
          "estacionamientos": {
            "type": "string",
            "description": "Número de estacionamientos."
          },
          "antiguedad_anos": {
            "$ref": "#/components/schemas/NumericFormValue",
            "description": "Antigüedad del inmueble en años."
          },
          "estado_conservacion": {
            "type": "string",
            "enum": [
              "Excelente",
              "Muy Bueno",
              "Bueno",
              "Regular",
              "Requiere Remodelación"
            ],
            "description": "Estado de conservación capturado por el formulario."
          },
          "usoSuelo": {
            "type": "string",
            "enum": [
              "Habitacional",
              "Comercial",
              "Industrial",
              "Mixto"
            ],
            "description": "Uso de suelo capturado por el formulario."
          },
          "precio_deseado_mxn": {
            "$ref": "#/components/schemas/NumericFormValue",
            "description": "Precio de venta deseado en pesos mexicanos, sin comas."
          },
          "amenidades": {
            "type": "string",
            "description": "Lista separada por comas de amenidades seleccionadas."
          },
          "acepto": {
            "type": "string",
            "description": "Valor enviado por el checkbox de aceptación legal del formulario."
          }
        }
      },
      "ValuationSuccessResponse": {
        "type": "object",
        "required": [
          "success",
          "solicitudId",
          "message"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "solicitudId": {
            "type": "integer",
            "description": "Identificador interno de la solicitud."
          },
          "message": {
            "type": "string"
          },
          "detalles": {
            "type": "object",
            "properties": {
              "ubicacion": {
                "type": "string"
              },
              "tipo_inmueble": {
                "type": "string"
              },
              "superficie": {
                "oneOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string"
                  }
                ]
              }
            }
          },
          "nota": {
            "type": "string"
          },
          "processingTime": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "detalles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-avluoinm24": {
    "service_type": "valuacion_inmobiliaria_estimada",
    "status": "active",
    "official_appraisal": false,
    "legal_validity": false,
    "coverage": [
      "CDMX",
      "Estado de México",
      "Morelos",
      "Quintana Roo"
    ],
    "limitations": [
      "No sustituye avalúo oficial.",
      "No tiene validez bancaria, notarial, fiscal, judicial ni administrativa.",
      "La estimación depende de datos proporcionados y referencias de mercado disponibles."
    ]
  }
}