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')
          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
      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