{
  "openapi": "3.1.0",
  "info": {
    "title": "COSTOCERO.MX · API Agéntica de Ingeniería de Costos",
    "version": "1.0.0",
    "description": "Especificación oficial de la API de COSTOCERO.MX para agentes de Inteligencia Artificial (LLMs), automatizaciones y sistemas de cotización técnica de naves industriales, centros logísticos y edificación comercial en México.",
    "contact": {
      "name": "COSTOCERO.MX · Ingeniería de Costos",
      "url": "https://costocero.mx",
      "email": "contacto@costocero.mx"
    },
    "license": {
      "name": "Propietario · Uso autorizado para clientes y agentes de IA"
    }
  },
  "servers": [
    {
      "url": "https://costocero.mx",
      "description": "Servidor de Producción Cloudflare Pages"
    }
  ],
  "paths": {
    "/api/leads": {
      "post": {
        "summary": "Registrar solicitud de cotización técnica o evaluación de obra",
        "description": "Permite registrar un proyecto para análisis paramétrico, elaboración de catálogo analítico de conceptos o auditoría de estimaciones en México.",
        "operationId": "solicitarCotizacionObra",
        "tags": [
          "Cotizaciones y Leads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadSubmission"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Solicitud recibida exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "folio": {
                      "type": "string",
                      "example": "CC-20261027-4821"
                    },
                    "message": {
                      "type": "string",
                      "example": "Solicitud registrada con éxito. Un ingeniero de costos te contactará en menos de 24 horas."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error en formato de datos, teléfono inválido o falta de aceptación de privacidad",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "El payload excede el límite de 10 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Límite de tasa excedido (máximo 5 peticiones por IP cada 10 minutos)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LeadSubmission": {
        "type": "object",
        "required": [
          "nombre",
          "telefono",
          "correo",
          "privacyAccepted"
        ],
        "properties": {
          "nombre": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "Nombre completo del solicitante o representante de la empresa",
            "example": "Ing. Carlos Mendoza"
          },
          "telefono": {
            "type": "string",
            "pattern": "^[\\d\\s+\\-().]{8,30}$",
            "description": "Teléfono de contacto o WhatsApp (mínimo 8 dígitos)",
            "example": "+52 222 383 2546"
          },
          "correo": {
            "type": "string",
            "format": "email",
            "maxLength": 160,
            "description": "Correo electrónico corporativo para recepción de propuesta",
            "example": "carlos.mendoza@inversiones.mx"
          },
          "perfil": {
            "type": "string",
            "enum": [
              "arquitecto_independiente",
              "despacho_arquitectura",
              "constructora_contratista",
              "inversionista_desarrollo",
              "estudiante_academico",
              "otro"
            ],
            "default": "inversionista_desarrollo",
            "description": "Perfil profesional o comercial del solicitante"
          },
          "tipoPresupuesto": {
            "type": "string",
            "enum": [
              "presupuesto_obra",
              "analisis_precios",
              "cuantificacion_param",
              "licitacion_privada",
              "auditoria_estimaciones",
              "asesoria_academica",
              "navez_industrial",
              "obra_infraestructura",
              "edificacion_comercial",
              "evaluacion_proyecto",
              "auditoria_presupuestal",
              "otro"
            ],
            "default": "navez_industrial",
            "description": "Tipo de servicio o tipología constructiva solicitada"
          },
          "descripcion": {
            "type": "string",
            "maxLength": 4000,
            "description": "Detalles del proyecto (superficie en m², ubicación y documentación disponible)",
            "example": "Construcción de nave industrial clase A de 5,000 m² en Puebla. Contamos con planos arquitectónicos y requerimos catálogo con APU."
          },
          "privacyAccepted": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Aceptación obligatoria del Aviso de Privacidad de COSTOCERO.MX"
          },
          "turnstileToken": {
            "type": "string",
            "description": "Token de verificación de seguridad Cloudflare Turnstile emitido en el frontend"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "Por favor ingresa un correo electrónico válido."
          }
        }
      }
    }
  }
}