{
  "openapi": "3.1.0",
  "info": {
    "title": "Los Brother's Jamay API",
    "version": "1.0.0",
    "description": "API oficial y especificación de funciones para agentes de IA de Los Brother's Jamay, taller especializado en reparación de celulares y servicio técnico en Jamay, Jalisco, México. Permite consultar información oficial del negocio (NAP), servicios de reparación disponibles, catálogo de marcas y modelos, y estimar cotizaciones de reparación.",
    "contact": {
      "name": "Los Brother's Jamay",
      "url": "https://www.losbrothers.shop/contact",
      "email": "contacto@losbrothers.shop"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.losbrothers.shop/privacy"
    }
  },
  "servers": [
    {
      "url": "https://www.losbrothers.shop",
      "description": "Servidor oficial de producción"
    }
  ],
  "paths": {
    "/api/store-info": {
      "get": {
        "operationId": "getStoreInfo",
        "summary": "Obtener datos oficiales del taller y contacto",
        "description": "Devuelve la información de contacto oficial (NAP), nombre comercial, dirección física en Jamay, coordenadas GPS, horarios y zonas atendidas en la Región Ciénega.",
        "responses": {
          "200": {
            "description": "Información oficial del negocio",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreInfo"
                }
              }
            }
          },
          "500": {
            "description": "Error interno del servidor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/services": {
      "get": {
        "operationId": "listRepairServices",
        "summary": "Listar servicios de reparación disponibles",
        "description": "Devuelve la lista de servicios técnicos que realiza el taller (pantallas OLED/AMOLED/Incell, baterías, centro de carga, cámaras, placa madre, equipo mojado) con entrega el mismo día y garantía por escrito.",
        "responses": {
          "200": {
            "description": "Listado de servicios de reparación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RepairService"
                      }
                    },
                    "diagnosticProtocol": {
                      "type": "string",
                      "example": "Pruebas de entrada (al recibir el celular) y de salida (antes de entregarlo)"
                    },
                    "warranty": {
                      "type": "string",
                      "example": "15 días a 2 meses por escrito según la refacción instalada"
                    }
                  },
                  "required": [
                    "services",
                    "diagnosticProtocol",
                    "warranty"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Consultar catálogo de marcas y modelos",
        "description": "Devuelve las marcas atendidas (Apple iPhone, Samsung Galaxy, Xiaomi, Motorola, Huawei, Honor, Oppo) y los modelos con disponibilidad de refacciones.",
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "description": "Filtro opcional por slug o identificador de marca (ej. 'apple', 'samsung', 'xiaomi', 'motorola')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catálogo de marcas y modelos atendidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Brand"
                      }
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PhoneModel"
                      }
                    }
                  },
                  "required": [
                    "brands",
                    "models"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/quote": {
      "post": {
        "operationId": "estimateRepairQuote",
        "summary": "Estimar viabilidad y generar cotización de reparación",
        "description": "Permite a un agente de IA o usuario solicitar estimación técnica para una marca, modelo y problema específico, retornando viabilidad, plazo de entrega (el mismo día), garantía escrita y enlace directo a WhatsApp.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estimación de reparación generada con éxito",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida o datos faltantes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StoreInfo": {
        "type": "object",
        "properties": {
          "brandName": {
            "type": "string",
            "example": "Los Brother's Jamay"
          },
          "businessName": {
            "type": "string",
            "example": "Los Brother's"
          },
          "description": {
            "type": "string",
            "example": "Taller especializado en reparación de celulares y servicio técnico en Jamay, Jalisco."
          },
          "address": {
            "type": "object",
            "properties": {
              "street": {
                "type": "string",
                "example": "Prol. Ramón Arizaga #400, Col. El Trompo"
              },
              "city": {
                "type": "string",
                "example": "Jamay"
              },
              "region": {
                "type": "string",
                "example": "Jalisco"
              },
              "postalCode": {
                "type": "string",
                "example": "47902"
              },
              "country": {
                "type": "string",
                "example": "México"
              }
            },
            "required": [
              "street",
              "city",
              "region",
              "postalCode",
              "country"
            ]
          },
          "coordinates": {
            "type": "object",
            "properties": {
              "latitude": {
                "type": "number",
                "example": 20.2993487
              },
              "longitude": {
                "type": "number",
                "example": -102.7028598
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "phone": {
                "type": "string",
                "example": "+523921917260"
              },
              "phoneFormatted": {
                "type": "string",
                "example": "+52 392 191 7260"
              },
              "email": {
                "type": "string",
                "example": "contacto@losbrothers.shop"
              },
              "whatsappUrl": {
                "type": "string",
                "example": "https://api.whatsapp.com/send?phone=523921917260"
              }
            },
            "required": [
              "phone",
              "phoneFormatted",
              "email",
              "whatsappUrl"
            ]
          },
          "hours": {
            "type": "object",
            "properties": {
              "mondayToSaturday": {
                "type": "string",
                "example": "10:00–15:00 y 16:00–21:00"
              },
              "sunday": {
                "type": "string",
                "example": "Cerrado"
              }
            },
            "required": [
              "mondayToSaturday",
              "sunday"
            ]
          },
          "coverageAreas": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Jamay",
              "Ocotlán",
              "La Barca",
              "Poncitlán"
            ]
          },
          "warranty": {
            "type": "string",
            "example": "15 días a 2 meses por escrito según la pieza"
          }
        },
        "required": [
          "brandName",
          "businessName",
          "description",
          "address",
          "coordinates",
          "contact",
          "hours",
          "coverageAreas",
          "warranty"
        ]
      },
      "RepairService": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "pantalla"
          },
          "name": {
            "type": "string",
            "example": "Cambio de Pantalla"
          },
          "description": {
            "type": "string",
            "example": "Display OLED, AMOLED o Incell con prueba de táctil."
          },
          "turnaround": {
            "type": "string",
            "example": "El mismo día"
          },
          "warranty": {
            "type": "string",
            "example": "15 días a 2 meses por escrito"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "turnaround",
          "warranty"
        ]
      },
      "Brand": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "apple"
          },
          "name": {
            "type": "string",
            "example": "Apple iPhone"
          },
          "popular": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "id",
          "name",
          "popular"
        ]
      },
      "PhoneModel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ip-15"
          },
          "brandId": {
            "type": "string",
            "example": "apple"
          },
          "name": {
            "type": "string",
            "example": "iPhone 15 / 15 Plus"
          },
          "popular": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "id",
          "brandId",
          "name",
          "popular"
        ]
      },
      "QuoteRequest": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string",
            "description": "Marca del celular (ej. Apple, Samsung, Xiaomi)"
          },
          "model": {
            "type": "string",
            "description": "Modelo del dispositivo (ej. iPhone 13, Galaxy S23)"
          },
          "issue": {
            "type": "string",
            "description": "Descripción del fallo técnico (ej. pantalla rota, batería degradada, centro de carga, celular mojado)"
          }
        },
        "required": [
          "brand",
          "issue"
        ]
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "estimated"
          },
          "brand": {
            "type": "string",
            "example": "Apple"
          },
          "model": {
            "type": "string",
            "example": "iPhone 13"
          },
          "issue": {
            "type": "string",
            "example": "pantalla rota"
          },
          "estimatedTurnaround": {
            "type": "string",
            "example": "El mismo día (sujeto a existencia de la refacción en inventario)"
          },
          "warranty": {
            "type": "string",
            "example": "15 días a 2 meses por escrito contra defectos de fábrica"
          },
          "recommendation": {
            "type": "string",
            "example": "Revisión en el mostrador sin costo. Se realizarán pruebas de entrada y de salida."
          },
          "whatsappUrl": {
            "type": "string",
            "example": "https://api.whatsapp.com/send?phone=523921917260"
          }
        },
        "required": [
          "status",
          "brand",
          "estimatedTurnaround",
          "warranty",
          "recommendation",
          "whatsappUrl"
        ]
      },
      "ApiErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "Endpoint no encontrado"
              },
              "hint": {
                "type": "string",
                "example": "Consulta /openapi.json o /docs para ver los endpoints disponibles."
              }
            },
            "required": [
              "code",
              "message",
              "hint"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}