{
  "openapi": "3.0.3",
  "info": {
    "title": "The Neura Brand · API de la empresa",
    "version": "1.0.0",
    "description": "CRM y calendario de UNA empresa cliente de Neurágora. Cada clave de API (se crea en Neurágora, Ventas, Conectar, Conexiones) solo abre los datos de su propia empresa. Límite: 120 llamadas por minuto. También disponible como servidor MCP en /api/mcp-empresa.php (la misma lógica). Los avisos de salida (webhooks) llevan la cabecera X-TNB-Firma: sha256=HMAC_SHA256(secreto, X-TNB-Fecha + '.' + cuerpo)."
  },
  "servers": [{ "url": "/api/v1" }],
  "security": [{ "bearer": [] }],
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Clave de API: tnb_ seguida de 48 caracteres hexadecimales." } },
    "schemas": {
      "Contacto": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "nombre": { "type": "string" }, "whatsapp": { "type": "string" }, "email": { "type": "string" },
          "temperatura": { "type": "string", "enum": ["caliente", "tibio", "frio"] }, "estado": { "type": "string" },
          "nota": { "type": "string" }, "proximo": { "type": "string" }, "seguimiento": { "type": "string", "description": "AAAA-MM-DD" },
          "valor": { "type": "number", "nullable": true }
        }
      },
      "ContactoEntrada": {
        "type": "object", "required": ["nombre"],
        "properties": {
          "nombre": { "type": "string" }, "whatsapp": { "type": "string", "description": "Con código de país." }, "email": { "type": "string" },
          "temperatura": { "type": "string", "enum": ["caliente", "tibio", "frio"] }, "nota": { "type": "string" }, "proximo": { "type": "string" },
          "seguimiento": { "type": "string", "description": "AAAA-MM-DD" }, "valor": { "type": "number" }
        }
      },
      "CitaEntrada": {
        "type": "object", "required": ["cliente", "fecha", "hora"],
        "properties": {
          "cliente": { "type": "string" }, "whatsapp": { "type": "string" }, "email": { "type": "string" },
          "fecha": { "type": "string", "description": "AAAA-MM-DD" }, "hora": { "type": "string", "description": "HH:MM, 24 horas" },
          "personas": { "type": "integer" }, "nota": { "type": "string" }, "avisar": { "type": "boolean", "description": "Enviar correo de confirmación." }
        }
      },
      "Error": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } }
    }
  },
  "paths": {
    "/contactos": {
      "get": {
        "summary": "Lista los contactos del CRM", "operationId": "crm_listar_contactos",
        "parameters": [{ "name": "estado", "in": "query", "schema": { "type": "string", "enum": ["activo", "ganado", "perdido", "recuperar"] } }],
        "responses": { "200": { "description": "Contactos" } }
      },
      "post": {
        "summary": "Crea un contacto (o actualiza al que tenga el mismo WhatsApp o correo)", "operationId": "crm_guardar_contacto",
        "description": "Requiere el permiso escribir.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactoEntrada" } } } },
        "responses": { "200": { "description": "{ ok, id, creado }" }, "422": { "description": "Datos inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }
      }
    },
    "/contactos/buscar": {
      "get": {
        "summary": "Busca contactos por nombre, WhatsApp o correo", "operationId": "crm_buscar_contacto",
        "parameters": [{ "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Contactos" } }
      }
    },
    "/contactos/{id}": {
      "post": {
        "summary": "Actualiza un contacto", "operationId": "crm_actualizar_contacto", "description": "Requiere el permiso escribir.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactoEntrada" } } } },
        "responses": { "200": { "description": "{ ok, id, creado: false }" } }
      }
    },
    "/contactos/{id}/estado": {
      "post": {
        "summary": "Cambia el estado de un contacto", "operationId": "crm_cambiar_estado", "description": "Requiere el permiso escribir.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["accion"], "properties": {
          "accion": { "type": "string", "enum": ["contactado", "respondio", "ganado", "perdido", "recuperado", "reabrir"] },
          "motivo": { "type": "string", "enum": ["precio", "momento", "pensarlo", "decide_otro", "ya_tiene", "no", "otro"] } } } } } },
        "responses": { "200": { "description": "{ ok }" } }
      }
    },
    "/horarios": {
      "get": {
        "summary": "Horarios libres de un día", "operationId": "calendario_ver_horarios",
        "parameters": [
          { "name": "fecha", "in": "query", "required": true, "schema": { "type": "string" }, "description": "AAAA-MM-DD" },
          { "name": "personas", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "{ ok, fecha, horarios: [{hora, quedan}] }" } }
      }
    },
    "/citas": {
      "get": {
        "summary": "Citas, reservas o clases en un rango", "operationId": "calendario_listar_citas",
        "parameters": [{ "name": "desde", "in": "query", "schema": { "type": "string" } }, { "name": "hasta", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Eventos" } }
      },
      "post": {
        "summary": "Agenda una cita, reserva o inscripción", "operationId": "calendario_agendar", "description": "Requiere el permiso escribir. Respeta el horario y el cupo.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitaEntrada" } } } },
        "responses": { "200": { "description": "{ ok, id, correo_enviado }" }, "422": { "description": "Horario no disponible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }
      }
    },
    "/citas/{id}/cancelar": {
      "post": {
        "summary": "Cancela una cita", "operationId": "calendario_cancelar", "description": "Requiere el permiso escribir.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "avisar": { "type": "boolean" } } } } } },
        "responses": { "200": { "description": "{ ok, correo_enviado }" } }
      }
    }
  }
}
