openapi: 3.1.0
info:
  title: Pepperoni.tatar API
  version: "2.1.0"
  description: >
    Halal meat products and Tatar pastries catalog by Kazan Delicacies (Казанские Деликатесы).
    62 products across 3 sections: Frozen, Refrigerated, Bakery.
    Live prices synced from Google Sheets. Prices in 7 currencies (RUB, USD, KZT, UZS, KGS, BYN, AZN).
    Halal certified #614A/2024 (DUM RT). HACCP. Private Label available.
  contact:
    name: Казанские Деликатесы / Kazan Delicacies
    email: info@kazandelikates.tatar
    url: https://kazandelikates.tatar
  license:
    name: Public API — no authentication required
    url: https://api.pepperoni.tatar
servers:
  - url: https://api.pepperoni.tatar
    description: Production (Russia, reverse proxy)
  - url: https://pepperoni-api.vercel.app
    description: Direct (Vercel, global CDN)
security: []
paths:
  /api/products:
    get:
      tags:
        - Products
      summary: Product catalog (live from Google Sheets)
      description: >
        Returns current product data and prices synced with Google Sheets.
        Updated on each request, cached for 1 hour.
        Supports search, filtering by section/category/SKU, and language selection.
      operationId: getProducts
      parameters:
        - name: search
          in: query
          description: Search by name, category, SKU, meatType or description
          schema:
            type: string
            examples:
              - пепперони
              - beef
              - KD-015
        - name: section
          in: query
          description: Filter by section
          schema:
            type: string
            enum: [Заморозка, Охлаждённая продукция, Выпечка]
        - name: category
          in: query
          description: Filter by category
          schema:
            type: string
            examples:
              - Топпинги
              - Сосиски гриль для хот-догов
              - Toppings
        - name: sku
          in: query
          description: Exact SKU match
          schema:
            type: string
            example: KD-015
        - name: lang
          in: query
          description: Response language (ru = Russian, en = English with translated names)
          schema:
            type: string
            enum: [ru, en]
            default: ru
      responses:
        '200':
          description: Product catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
  /api/export:
    get:
      tags:
        - Export
      summary: Download catalog as Excel (.xlsx) or CSV
      description: >
        Returns a downloadable file with all products and prices.
        Supports language, currency, VAT selection and format choice.
      operationId: exportCatalog
      parameters:
        - name: lang
          in: query
          schema:
            type: string
            enum: [ru, en]
            default: ru
        - name: currency
          in: query
          schema:
            type: string
            enum: [RUB, USD, KZT, UZS, KGS, BYN, AZN]
            default: RUB
        - name: vat
          in: query
          description: Include VAT (only for RUB)
          schema:
            type: boolean
            default: true
        - name: format
          in: query
          schema:
            type: string
            enum: [xlsx, csv]
            default: xlsx
      responses:
        '200':
          description: Downloadable file
          headers:
            Content-Disposition:
              schema:
                type: string
                example: 'attachment; filename="Kazan_Delicacies_USD.xlsx"'
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
            text/csv:
              schema:
                type: string
  /api/mcp:
    post:
      tags:
        - MCP
      summary: Model Context Protocol (Streamable HTTP)
      description: >
        Stateless MCP server for AI clients (Claude Desktop, Cursor).
        Tools: search_products, get_product, get_catalog, get_certification,
        get_delivery_info, submit_inquiry.
        Manifest: https://pepperoni.tatar/.well-known/mcp.json
      operationId: mcpStreamableHttp
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                type: object
    get:
      tags:
        - MCP
      summary: MCP SSE stream (optional)
      description: Streamable HTTP GET for server-sent events when supported by the client.
      operationId: mcpSseStream
      responses:
        '200':
          description: SSE stream
  /api/health:
    get:
      tags:
        - System
      summary: API health check
      operationId: healthCheck
      responses:
        '200':
          description: API status and endpoint list
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  version:
                    type: string
                    example: "2.1.0"
                  endpoints:
                    type: object
                    description: "Map of available API endpoints"
  /api/stats:
    get:
      tags:
        - System
      summary: AI bot visit analytics
      operationId: getStats
      responses:
        '200':
          description: Visit statistics with bot detection
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    type: string
                  totalVisits:
                    type: integer
                  botVisits:
                    type: integer
                  humanVisits:
                    type: integer
                  botBreakdown:
                    type: object
                    description: "Map of bot name to visit count"
                  countryBreakdown:
                    type: object
                    description: "Map of country code to visit count"
                  recentBotVisits:
                    type: array
                    items:
                      type: object
                      properties:
                        bot:
                          type: string
                        path:
                          type: string
                        country:
                          type: string
                        time:
                          type: string
                  recentVisits:
                    type: array
                    items:
                      type: object
                      properties:
                        bot:
                          type: string
                        path:
                          type: string
                        country:
                          type: string
                        time:
                          type: string
                        ua:
                          type: string
                  note:
                    type: string
  /api/search:
    get:
      tags:
        - Search
      summary: Fast product search (optimized for AI agents)
      description: >
        Lightweight search endpoint returning compact results.
        For AI agents, prefer this over /api/products for faster responses.
        Returns max 10 results by default (up to 50).
      operationId: searchProducts
      parameters:
        - name: q
          in: query
          required: true
          description: Search query (name, category, SKU, meat type)
          schema:
            type: string
            example: pepperoni
        - name: lang
          in: query
          schema:
            type: string
            enum: [ru, en]
            default: ru
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 50
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalMatches:
                    type: integer
                  returned:
                    type: integer
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        sku:
                          type: string
                        name:
                          type: string
                        category:
                          type: string
                        price:
                          type: number
                        priceCurrency:
                          type: string
  /api/product/{sku}:
    get:
      tags:
        - Products
      summary: Single product by SKU
      description: Returns full product details for a specific SKU.
      operationId: getProductBySku
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
            example: KD-015
        - name: lang
          in: query
          schema:
            type: string
            enum: [ru, en]
            default: ru
      responses:
        '200':
          description: Full product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
  /products.json:
    get:
      tags:
        - Products
      summary: Static product catalog (updated daily by GitHub Actions)
      operationId: getStaticProducts
      responses:
        '200':
          description: Static JSON catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
components:
  securitySchemes: {}
  schemas:
    CatalogResponse:
      type: object
      required:
        - dateModified
        - totalProducts
        - products
      properties:
        '@context':
          type: string
          const: https://schema.org
        '@type':
          type: string
          const: DataCatalog
        dateModified:
          type: string
          format: date-time
          example: "2026-02-27T12:00:00.000Z"
        totalProducts:
          type: integer
          example: 77
        source:
          type: string
          example: "Google Sheets (live sync — 3 sheets)"
        sections:
          type: array
          items:
            type: string
          example: [Заморозка, Охлаждённая продукция, Выпечка]
        filters:
          type: object
          description: Active filters in the request (null if not applied)
        b2b:
          $ref: '#/components/schemas/B2BInfo'
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    B2BInfo:
      type: object
      properties:
        halal_cert:
          type: object
          properties:
            body:
              type: string
              example: Комитет по стандарту Халяль ДУМ РТ
            number:
              type: string
              example: "614A/2024"
            country:
              type: string
              example: Russia
        quality_system:
          type: string
          example: HACCP
        customs_union_cert:
          type: boolean
          example: true
        manufacturer:
          type: object
          properties:
            name:
              type: string
              example: ООО «Казанские Деликатесы»
            inn:
              type: string
              example: "1686021074"
            ogrn:
              type: string
              example: "1221600096893"
        delivery_terms:
          type: string
          example: EXW Kazan, Russia (Incoterms 2020)
        private_label:
          type: boolean
          example: true
        no_pork:
          type: boolean
          example: true
        no_gmo:
          type: boolean
          example: true
        no_transglutaminase:
          type: boolean
          example: true
    Offer:
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://pepperoni.tatar
        priceCurrency:
          type: string
          example: RUB
        price:
          type: string
          description: Price including VAT (RUB)
          example: "290.00"
        priceExclVAT:
          type: string
          description: Price excluding VAT (RUB)
          example: "263.64"
        pricePerUnit:
          type: string
          description: Per-unit price for bakery items
          example: "56.00"
        pricePerBox:
          type: string
          description: Per-box price for bakery items
          example: "2688.00"
        availability:
          type: string
          example: https://schema.org/InStock
        vatIncluded:
          type: boolean
          description: Whether price includes VAT
          example: true
        exportPrices:
          type: object
          description: Prices in export currencies (all excl. VAT)
          additionalProperties:
            type: number
          example:
            USD: 3.41
            KZT: 1712.05
            UZS: 41483.77
            KGS: 298.46
            BYN: 9.78
            AZN: 5.80
        deliveryTerms:
          type: string
          example: EXW Kazan Russia
        incoterms:
          type: string
          example: EXW
    Product:
      type: object
      required:
        - name
        - sku
        - offers
      properties:
        name:
          type: string
          example: Сосиски «Из говядины» (80 г × 6 шт)
        name_ru:
          type: string
          description: Original Russian name (when lang=en)
        sku:
          type: string
          example: KD-001
        ean:
          type: string
          description: EAN/GTIN barcode
          example: "4680638720318"
        section:
          type: string
          description: Product line
          example: Заморозка
        category:
          type: string
          example: Сосиски гриль для хот-догов
        weight:
          type: string
          description: Unit weight for pricing
          example: "0.48 кг"
        qtyPerBox:
          type: string
          description: Units per shipping box
          example: "6"
        brand:
          type: string
          example: Казанские Деликатесы
        description:
          type: string
        meatType:
          type: string
          description: Type of meat used
          example: говядина, курица
        certification:
          type: string
          example: Halal
        image:
          type: string
          format: uri
          description: Primary product image (Cloudinary)
        imageMain:
          type: string
          format: uri
          description: Main product photo
        imagePack:
          type: string
          format: uri
          description: Product packaging photo
        imageSlice:
          type: string
          format: uri
          description: Product slice/cross-section photo
        offers:
          $ref: '#/components/schemas/Offer'
        shelfLife:
          type: string
          description: Shelf life
          example: "360 суток"
        storage:
          type: string
          description: Storage temperature
          example: "–18°C"
        hsCode:
          type: string
          description: HS/ТН ВЭД customs code
          example: "160100"
        countryOfOrigin:
          type: string
          example: RU
        halal_cert:
          type: object
          properties:
            body:
              type: string
            number:
              type: string
        quality_system:
          type: string
          example: HACCP
        private_label:
          type: boolean
        export_ready:
          type: boolean
        min_order:
          type: string
          description: Minimum order quantity
          example: "6 packs (1 box)"
        pallet_qty:
          type: string
          description: Boxes per pallet