openapi: 3.0.0
info:
  title: Rakuichi System - Integration APIs
  description: |
    APIs for integration between Facility Owner System and Rakuichi System.
    
    ## Authentication
    All APIs require API Key in X-API-Key header.
  version: 1.0.0
  contact:
    name: Columbusman Tech

security:
  - ApiKeyAuth: []

paths:
  /orders:
    get:
      tags:
        - Orders
      summary: Get Order List
      description: |
        Retrieve a list of orders with search and filter functionality. This API is only active for orders integrated with Rakuichi System.
        
        ## Query Parameters
        All parameters are optional and can be combined for advanced search.
        
        ## Search Fields
        - `freeword`: Searches across place, admin_account_name, user_account_name fields
        - Date ranges: `order_date_from` (created_at from), `order_date_to` (created_at to), `start_date`, `end_date`
        - Exact matches: `order_id`, `facility_id`, `owner_no`, `order_status`
        - Partial matches: `facility_name`, `user_company_name`, `field_manager_name`
        
        ## Sorting
        - Default: `created_at desc` (newest orders first)
        - Available fields: `created_at`, `id`
        - Directions: `asc` (ascending), `desc` (descending)
        
        ## Response Fields
        - `orders`: Array of order objects with basic information
        - `pagination`: Pagination information (if applicable)
        
        ## Error Codes
        - `200`: Success - Orders found and returned
        - `400`: Bad Request - Invalid query parameters
        - `401`: Unauthorized - Invalid or missing API key
        - `500`: Internal Server Error - Server error
      parameters:
        - name: order_id
          in: query
          required: false
          description: Filter by specific order ID
          schema:
            type: integer
            minimum: 1
            example: 12345
        - name: facility_id
          in: query
          required: false
          description: Filter by facility ID
          schema:
            type: integer
            minimum: 1
            example: 1001
        - name: facility_name
          in: query
          required: false
          description: Filter by facility name (partial match)
          schema:
            type: string
            example: "Tokyo Convention"
        - name: owner_no
          in: query
          required: false
          description: Filter by owner number
          schema:
            type: string
            example: "o123"
        - name: order_status
          in: query
          required: false
          description: Filter by order status
          schema:
            type: integer
            example: 2
        - name: user_company_name
          in: query
          required: false
          description: Filter by user company name (partial match)
          schema:
            type: string
            example: "ABC Corporation"
        - name: field_manager_name
          in: query
          required: false
          description: Filter by field manager name (partial match)
          schema:
            type: string
            example: "John Doe"
        - name: order_date_from
          in: query
          required: false
          description: Filter by order creation date from (created_at from) (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2024-01-01"
        - name: order_date_to
          in: query
          required: false
          description: Filter by order creation date to (created_at to) (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2024-01-31"
        - name: start_date
          in: query
          required: false
          description: Filter by order start date from (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2024-01-15"
        - name: end_date
          in: query
          required: false
          description: Filter by order end date to (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2024-01-16"
        - name: freeword
          in: query
          required: false
          description: Search across place, admin_account_name, user_account_name fields
          schema:
            type: string
            example: "Tokyo"
        - name: page
          in: query
          required: false
          description: Page number for pagination (default:1)
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: per_page
          in: query
          required: false
          description: Number of items per page (default:20, max:100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
        - name: order_by
          in: query
          required: false
          description: Sort field (default:created_at desc)
          schema:
            type: string
            enum: [created_at, id]
            default: "created_at"
            example: "created_at"
        - name: order_direction
          in: query
          required: false
          description: Sort direction (default:desc)
          schema:
            type: string
            enum: [asc, desc]
            default: "desc"
            example: "desc"
      responses:
        '200':
          description: Success - Returns list of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/OrderList'
              example:
                success: true
                data:
                  orders:
                    - id: 12345
                      created_at: "2024-01-15T10:30:00Z"
                      facility_id: 1001
                      facility_name: "Tokyo Convention Center"
                      place: "Main Hall A"
                      user_company_name: "ABC Corporation"
                      commodity: "Event Equipment"
                      admin_account_name: "Admin User"
                      start_date: "2024-01-15"
                      end_date: "2024-01-16"
                      order_status:
                        order_status: 2
                    - id: 12346
                      created_at: "2024-01-16T14:20:00Z"
                      facility_id: 1002
                      facility_name: "Osaka Event Hall"
                      place: "Conference Room B"
                      user_company_name: "XYZ Company"
                      commodity: "Meeting Equipment"
                      admin_account_name: "Manager User"
                      start_date: "2024-01-20"
                      end_date: "2024-01-21"
                      order_status:
                        order_status: 1
                  pagination:
                    current_page: 1
                    per_page: 20
                    total: 2
                    total_pages: 1
                    has_next: false
                    has_prev: false
        
        '400':
          description: Bad Request - Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid date format"
                code: "INVALID_DATE_FORMAT"
        
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid or missing API key"
                code: "UNAUTHORIZED"
        
        '500':
          description: Internal Server Error - Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "INTERNAL_ERROR"

  /orders/{order_id}:
    get:
      tags:
        - Orders
      summary: Get Order Detail
      description: |
        Retrieve detailed information of an order based on order_id.
        This API is only active for orders integrated with Rakuichi System.
        
        ## Response Fields
        - All fields can return `null` if no data is available
        - `start_date`, `end_date`: format `YYYY-MM-DD`
        - `start_at`, `end_at`: format `HH:mm:ss` (can be null)
        - `total_price`, `total_tax_price`, `tax`: integer (can be null)
        
        ## Error Codes
        - `200`: Success - Order found and returned
        - `400`: Bad Request - Invalid order_id format (string instead of integer)
        - `401`: Unauthorized - Invalid or missing API key
        - `404`: Not Found - Order does not exist
        - `500`: Internal Server Error - Server error
      parameters:
        - name: order_id
          in: path
          required: true
          description: ID of the order to retrieve information (must be integer)
          schema:
            type: integer
            minimum: 1
            example: 12345
      responses:
        '200':
          description: Success - Returns order information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/OrderDetail'
              example:
                success: true
                data:
                  id: 12345
                  facility_id: 1001
                  facility_name: "Tokyo Convention Center"
                  owner_no: "o123"
                  place: "Main Hall A"
                  prefectures: "Tokyo"
                  ward: "Chiyoda"
                  block_address: "1-1-1 Marunouchi"
                  building: "Marunouchi Building"
                  breadth: "100m²"
                  total_price: 500000
                  total_tax_price: 550000
                  tax: 50000
                  user_company_name: "ABC Corporation"
                  start_date: "2024-01-15"
                  end_date: "2024-01-16"
                  commodity: "Event Equipment"
                  commodity_detail: "Audio system, lighting"
                  field_manager_tel: "03-1234-5678"
                  number_of_visitors: 100
                  visitor: "General public"
                  start_at: "09:00:00"
                  end_at: "18:00:00"
                  carry_in_time: "08:00"
                  carry_out_time: "19:00"
                  carry_car: "2-ton truck"
                  carry_car_remark: "Enter from back gate"
                  power: "100V, 200V available"
                  power_detail: "10 outlets available"
                  equipment: "Tables, chairs"
                  equipment_detail: "20 tables, 100 chairs"
                  equipment_request: "Additional lighting needed"
                  handout: "Event brochure"
                  shop_guide: "Available on request"
                  shop_guide_tel: "03-1234-5679"
                  remark: "Special setup required"
                  order_status:
                    remark: "Order confirmed"
                    order_status: 2
        
        '400':
          description: Bad Request - Invalid order_id format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Order ID must be a valid integer"
                code: "INVALID_ORDER_ID"
                details:
                  field: "order_id"
                  message: "Order ID must be a positive integer, received: 'abc123'"
        
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "API key is required"
                code: "MISSING_API_KEY"
        
        '404':
          description: Not Found - Order does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Order not found"
                code: "ORDER_NOT_FOUND"
                details:
                  order_id: 99999
                  message: "No order found with ID: 99999"
        
        '500':
          description: Internal Server Error - Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Database connection error"
                code: "DATABASE_ERROR"

  /orders/{order_id}/status:
    put:
      tags:
        - Orders
      summary: Update Order Status
      description: |
        Update order status and send notification emails to CLM sales staff and rakuichi_space.
        
        ## Business Logic
        This API is only active for orders integrated with Rakuichi System.
        
        ### For Confirmed Orders (実施確定)
        - Send confirmation email to CLM sales staff and rakuichi_space
        - Update order status to "Confirmed"
        - Add confirmation message to remarks
        - Record in memo: date, time, owner company name, updater name, status change
        
        ### For Impossible Orders (実施不可)
        - Send impossibility email to CLM sales staff and rakuichi_space
        - Update order status to "Impossible"
        - Add impossibility message to remarks
        - Record in memo: date, time, owner company name, updater name, status change
        
        ## Error Codes
        - `200`: Success - Order status updated and emails sent
        - `400`: Bad Request - Invalid status or missing required fields
        - `401`: Unauthorized - Invalid or missing API key
        - `404`: Not Found - Order does not exist
        - `500`: Internal Server Error - Server error
      parameters:
        - name: order_id
          in: path
          required: true
          description: ID of the order to update status
          schema:
            type: integer
            minimum: 1
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
                - remark
              properties:
                status:
                  type: integer
                  description: New order status
                  enum: [2, 3]
                  example: 2
                  x-enum-descriptions:
                    2: "Confirmed (実施確定)"
                    3: "Impossible (実施不可)"
                remark:
                  type: string
                  description: Status update remark/message
                  maxLength: 3000
                  example: "Order has been confirmed and scheduled"
            example:
              status: 2
              remark: "Order has been confirmed and scheduled for the requested dates"
      responses:
        '200':
          description: Success - Order status updated and emails sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      order_id:
                        type: integer
                        description: Updated order ID
                        example: 12345
                      status:
                        type: integer
                        description: New order status
                        example: 2
                      updated_at:
                        type: string
                        format: date-time
                        description: Update timestamp
                        example: "2024-01-15T14:30:00Z"
                      emails_sent:
                        type: array
                        description: List of email addresses where notifications were sent
                        items:
                          type: string
                        example: ["clm-sales@example.com", "rakuichi-space@example.com"]
              example:
                success: true
                data:
                  order_id: 12345
                  status: 2
                  updated_at: "2024-01-15T14:30:00Z"
                  emails_sent: ["clm-sales@example.com", "rakuichi-space@example.com"]
        
        '400':
          description: Bad Request - Invalid status or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid order status"
                code: "INVALID_STATUS"
                details:
                  field: "status"
                  message: "Status must be 2 (Confirmed) or 3 (Impossible), received: 1"
        
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid or missing API key"
                code: "UNAUTHORIZED"
        
        '404':
          description: Not Found - Order does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Order not found"
                code: "ORDER_NOT_FOUND"
                details:
                  order_id: 99999
                  message: "No order found with ID: 99999"
        
        '500':
          description: Internal Server Error - Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Failed to send notification emails"
                code: "EMAIL_ERROR"

  /orders/{order_id}/calendar:
    post:
      tags:
        - Orders
      summary: Update Calendar for Order
      description: |
        Update calendar data in Rakuichi System when an order is created or updated.
        This API marks selected dates as unavailable (×) in Rakuichi System's facility calendar.
        The API is called automatically when an order is created or updated to sync calendar availability.
        
        ## Request Body
        - `place_id`: Place ID in the owner system
        - `reserved_days`: Array of reserved days with calendar and price information
        
        ## Integration Flow
        1. Order is created/updated in owner system
        2. Selected dates are stored in `place_calendar_relations` with value
        3. This API is called to sync with Rakuichi System
        4. Rakuichi System updates their table
      security:
        - ApiKeyAuth: []
      parameters:
        - name: order_id
          in: path
          required: true
          description: ID of the order to update calendar for
          schema:
            type: integer
            minimum: 1
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - place_id
                - reserved_days
              properties:
                place_id:
                  type: integer
                  description: Place ID in the owner system
                  example: 12345
                reserved_days:
                  type: array
                  description: Array of reserved days with calendar and price information
                  items:
                    type: object
                    required:
                      - selected_date
                      - selected_week
                      - special_price_type
                      - basic_sell_price
                      - change_sell_price
                    properties:
                      selected_date:
                        type: string
                        format: date
                        description: Selected date for the order
                        example: "2024-01-15"
                      selected_week:
                        type: integer
                        description: Day of week (0:Sunday, 1:Monday, 2:Tuesday, ..., 6:Saturday)
                        enum: [0, 1, 2, 3, 4, 5, 6]
                        example: 3
                      special_price_type:
                        type: integer
                        description: Price type (0:normal, 1:special)
                        enum: [0, 1]
                        example: 1
                      basic_sell_price:
                        type: integer
                        description: Basic selling price
                        example: 4000
                      change_sell_price:
                        type: integer
                        description: Modified selling price
                        example: 5000
            example:
              place_id: 12345
              reserved_days:
                - selected_date: "2024-01-15"
                  selected_week: 3
                  special_price_type: 1
                  basic_sell_price: 4000
                  change_sell_price: 5000
                - selected_date: "2024-01-16"
                  selected_week: 4
                  special_price_type: 1
                  basic_sell_price: 4000
                  change_sell_price: 5000
      responses:
        '200':
          description: Calendar updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Calendar updated successfully"
                  updated_dates:
                    type: array
                    items:
                      type: string
                      format: date
                    example: ["2024-01-15", "2024-01-16"]
              example:
                success: true
                message: "Calendar updated successfully"
                updated_dates: ["2024-01-15", "2024-01-16"]
        '400':
          description: Bad request - Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid calendar data"
                code: "INVALID_CALENDAR_DATA"
                details:
                  field: "calendar_data"
                  message: "Calendar data must contain valid dates and values"
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid API key"
                code: "INVALID_API_KEY"
        '404':
          description: Place not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Place not found"
                code: "PLACE_NOT_FOUND"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /place/{place_id}/calendar/sync:
    post:
      tags:
        - Place Integration
      summary: Sync Calendar Changes
      description: |
        Sync calendar changes to Rakuichi System when calendar is updated.
        This API is called when calendar data is modified (prices, availability).
        It sends only the changed calendar entries to Rakuichi System.
        
        ## Use Cases
        - Calendar price updates
        - Availability changes (△, ○, ×)
        - Special price settings
        - Calendar maintenance operations
        
        ## Request Body
        - `calendar_data`: Array of updated calendar entries
      security:
        - ApiKeyAuth: []
      parameters:
        - name: place_id
          in: path
          required: true
          description: ID of the place to sync calendar for
          schema:
            type: integer
            minimum: 1
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - changed_dates
                - calendar_data
              properties:
                calendar_data:
                  type: array
                  description: Array of updated calendar entries
                  items:
                    type: object
                    required:
                      - regist_date
                      - value
                      - special_price_type
                      - special_price_sell
                    properties:
                      regist_date:
                        type: string
                        format: date
                        description: Date that was updated
                        example: "2024-01-15"
                      value:
                        type: integer
                        description: Calendar value (1:△, 2:○, 3:×)
                        enum: [1, 2, 3]
                        example: 2
                      special_price_type:
                        type: integer
                        description: Price type (0:normal, 1:special)
                        enum: [0, 1]
                        example: 1
                      special_price_sell:
                        type: integer
                        nullable: true
                        description: Special price (sell value)
                        example: 6000
            example:
              calendar_data:
                - regist_date: "2024-01-15"
                  value: 2
                  special_price_type: 1
                  special_price_sell: 6000
                - regist_date: "2024-01-16"
                  value: 1
                  special_price_type: 0
                  special_price_sell: null
      responses:
        '200':
          description: Calendar synced successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Calendar synced successfully"
                  synced_dates:
                    type: array
                    items:
                      type: string
                      format: date
                    example: ["2024-01-15", "2024-01-16"]
              example:
                success: true
                message: "Calendar synced successfully"
                synced_dates: ["2024-01-15", "2024-01-16"]
        '400':
          description: Bad request - Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid sync data"
                code: "INVALID_SYNC_DATA"
                details:
                  field: "changed_dates"
                  message: "Changed dates array cannot be empty"
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid API key"
                code: "INVALID_API_KEY"
        '404':
          description: Place not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Place not found"
                code: "PLACE_NOT_FOUND"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /place/{place_id}/sync:
    post:
      tags:
        - Place Integration
      summary: Sync Place Data
      description: |
        Sync place information to Rakuichi System when place data is saved or updated.
        This API sends basic place information to Rakuichi System so they can update their facility data.
        The API is called automatically when place data is saved in the owner system.
        
        ## Integration Note
        Rakuichi System uses the concept of "facility" while the owner system uses "place".
        This API maps place data to facility data for Rakuichi System compatibility.
        
        ## Request Body
        Contains basic place information fields that Rakuichi System needs to maintain.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: place_id
          in: path
          required: true
          description: ID of the place to sync calendar for
          schema:
            type: integer
            minimum: 1
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - place_id
                - facility_id
                - place
              properties:
                place_id:
                  type: integer
                  description: Place ID in the owner system
                  example: 12345
                facility_id:
                  type: integer
                  description: Associated facility ID
                  example: 67890
                owner_place_id:
                  type: integer
                  description: Owner place ID
                  example: 12345
                place:
                  type: string
                  description: Name of the place
                  example: "Main Hall"
                owner_no:
                  type: string
                  nullable: true
                  description: Owner number
                  example: "OWNER001"
                breadth:
                  type: string
                  nullable: true
                  description: Size/dimensions of the place
                  example: "100m²"
                start_at:
                  type: string
                  format: time
                  nullable: true
                  description: Operating start time
                  example: "09:00:00"
                end_at:
                  type: string
                  format: time
                  nullable: true
                  description: Operating end time
                  example: "18:00:00"
                inout_door_flag:
                  type: integer
                  description: Indoor/outdoor flag (1:indoor, 2:outdoor)
                  enum: [1, 2]
                  example: 1
                inout_door_comment:
                  type: string
                  nullable: true
                  description: Indoor/outdoor comment
                  example: "Indoor with air conditioning"
                weekday_sell_price:
                  type: integer
                  nullable: true
                  description: Weekday selling price
                  example: 5000
                saturday_sell_price:
                  type: integer
                  nullable: true
                  description: Saturday selling price
                  example: 6000
                holiday_sell_price:
                  type: integer
                  nullable: true
                  description: Holiday selling price
                  example: 7000
                power_flag:
                  type: integer
                  description: Power availability flag (1:available, 2:not available)
                  enum: [1, 2]
                  example: 1
                power_comment:
                  type: string
                  nullable: true
                  description: Power comment
                  example: "100V, 200V available"
                desk_flag:
                  type: integer
                  description: Desk availability flag (1:available, 2:not available)
                  enum: [1, 2]
                  example: 1
                desk_comment:
                  type: string
                  nullable: true
                  description: Desk comment
                  example: "20 desks available"
                chair_flag:
                  type: integer
                  description: Chair availability flag (1:available, 2:not available)
                  enum: [1, 2]
                  example: 1
                chair_comment:
                  type: string
                  nullable: true
                  description: Chair comment
                  example: "100 chairs available"
                wifi_flag:
                  type: integer
                  description: WiFi availability flag (1:available, 2:not available)
                  enum: [1, 2]
                  example: 1
                wifi_comment:
                  type: string
                  nullable: true
                  description: WiFi comment
                  example: "Free WiFi available"
                food_flag:
                  type: integer
                  description: Food availability flag (1:available, 2:not available)
                  enum: [1, 2]
                  example: 1
                food_comment:
                  type: string
                  nullable: true
                  description: Food comment
                  example: "Catering service available"
                ngcommodity_flag:
                  type: integer
                  description: NG commodity flag (0:allowed, 1:not allowed)
                  enum: [0, 1]
                  example: 0
                ngcommodity_comment:
                  type: string
                  nullable: true
                  description: NG commodity comment
                  example: "No dangerous goods allowed"
                comment:
                  type: string
                  nullable: true
                  description: General comment about the place
                  example: "Large space suitable for events"
                caution_comment:
                  type: string
                  nullable: true
                  description: Caution/notice about the place
                  example: "Please clean up after use"
                invalid_week:
                  type: string
                  nullable: true
                  description: Invalid week information
                  example: "Monday, Tuesday"
                apply_expired:
                  type: string
                  nullable: true
                  description: Application expired information
                  example: "7 days before event"
                replay:
                  type: string
                  nullable: true
                  description: Replay information
                  example: "Available"
                replay_day:
                  type: string
                  nullable: true
                  description: Replay day information
                  example: "3 days"
                apply_caution_comment:
                  type: string
                  nullable: true
                  description: Application caution comment
                  example: "Please apply at least 1 week in advance"
                opening_caution_comment:
                  type: string
                  nullable: true
                  description: Opening caution comment
                  example: "Please arrive 30 minutes before start time"
                pre_meeting:
                  type: string
                  nullable: true
                  description: Pre-meeting information
                  example: "Required for large events"
                furniture:
                  type: string
                  nullable: true
                  description: Furniture information
                  example: "Tables, chairs, whiteboard"
                furniture_remark:
                  type: string
                  nullable: true
                  description: Furniture remark
                  example: "Additional furniture available on request"
                carriage:
                  type: string
                  nullable: true
                  description: Carriage information
                  example: "Available"
                carry_in_time:
                  type: string
                  nullable: true
                  description: Carry-in time
                  example: "2 hours before event"
                leaving_time:
                  type: string
                  nullable: true
                  description: Leaving time
                  example: "1 hour after event"
                cancel_policy:
                  type: string
                  nullable: true
                  description: Cancel policy
                  example: "50% refund if cancelled 3 days before"
                memo:
                  type: string
                  nullable: true
                  description: Internal memo
                  example: "Popular venue, book early"
                notification:
                  type: integer
                  description: Notification flag (1:enabled, 2:disabled)
                  enum: [1, 2]
                  example: 1
                notification_from:
                  type: integer
                  nullable: true
                  description: Notification from week
                  example: 2
                notification_to:
                  type: integer
                  nullable: true
                  description: Notification to week
                  example: 10
                owner_account:
                  type: integer
                  description: Owner account ID
                  example: 1
                created_user:
                  type: integer
                  description: Created user ID
                  example: 1
                calendar_last_updated_at:
                  type: string
                  format: date-time
                  description: Calendar last updated timestamp
                  example: "2024-01-15T10:30:00Z"
                status:
                  type: integer
                  description: Status of the place (1:active, 2:inactive)
                  enum: [1, 2]
                  example: 1
            example:
              place_id: 12345
              facility_id: 67890
              owner_place_id: 12345
              place: "Main Hall"
              owner_no: "OWNER001"
              breadth: "100m²"
              start_at: "09:00:00"
              end_at: "18:00:00"
              inout_door_flag: 1
              inout_door_comment: "Indoor with air conditioning"
              weekday_sell_price: 5000
              saturday_sell_price: 6000
              holiday_sell_price: 7000
              power_flag: 1
              power_comment: "100V, 200V available"
              desk_flag: 1
              desk_comment: "20 desks available"
              chair_flag: 1
              chair_comment: "100 chairs available"
              wifi_flag: 1
              wifi_comment: "Free WiFi available"
              food_flag: 1
              food_comment: "Catering service available"
              ngcommodity_flag: 0
              ngcommodity_comment: "No dangerous goods allowed"
              comment: "Large space suitable for events"
              caution_comment: "Please clean up after use"
              invalid_week: "Monday, Tuesday"
              apply_expired: "7 days before event"
              replay: "Available"
              replay_day: "3 days"
              apply_caution_comment: "Please apply at least 1 week in advance"
              opening_caution_comment: "Please arrive 30 minutes before start time"
              pre_meeting: "Required for large events"
              furniture: "Tables, chairs, whiteboard"
              furniture_remark: "Additional furniture available on request"
              carriage: "Available"
              carry_in_time: "2 hours before event"
              leaving_time: "1 hour after event"
              cancel_policy: "50% refund if cancelled 3 days before"
              memo: "Popular venue, book early"
              notification: 1
              notification_from: 2
              notification_to: 10
              owner_account: 1
              created_user: 1
              calendar_last_updated_at: "2024-01-15T10:30:00Z"
              status: 1
      responses:
        '200':
          description: Place data synced successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Place data synced successfully"
                  place_id:
                    type: integer
                    example: 12345
                  facility_id:
                    type: integer
                    example: 67890
              example:
                success: true
                message: "Place data synced successfully"
                place_id: 12345
                facility_id: 67890
        '400':
          description: Bad request - Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid place data"
                code: "INVALID_PLACE_DATA"
                details:
                  field: "place_name"
                  message: "Place name is required"
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid API key"
                code: "INVALID_API_KEY"
        '404':
          description: Place not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Place not found"
                code: "PLACE_NOT_FOUND"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /holiday-master:
    get:
      tags:
        - Holiday Master
      summary: Get holiday master data
      description: Retrieve holiday master data from Rakuichi System. This API returns holiday information including dates and names for specified date range.
      parameters:
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Start date for holiday search (YYYY-MM-DD)
          example: "2024-01-01"
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: End date for holiday search (YYYY-MM-DD)
          example: "2024-12-31"
        - name: holiday_date
          in: query
          schema:
            type: string
            format: date
          description: Specific holiday date to search (YYYY-MM-DD)
          example: "2024-01-01"
      responses:
        '200':
          description: Holiday master data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HolidayMaster'
              example:
                success: true
                data:
                  - holiday_id: 1
                    holiday_date: "2024-01-01"
                    holiday_name: "元日"
                  - holiday_id: 2
                    holiday_date: "2024-01-13"
                    holiday_name: "成人の日"
                  - holiday_id: 3
                    holiday_date: "2024-02-11"
                    holiday_name: "建国記念の日"
        '400':
          description: Bad request - Invalid date format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid date format"
                code: "INVALID_DATE_FORMAT"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /facility-categories:
    get:
      tags:
        - Facility Categories
      summary: Get facility categories
      description: Retrieve facility categories from Rakuichi System
      responses:
        '200':
          description: Facility categories retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FacilityCategory'
              example:
                success: true
                data:
                  - facility_category_id: 1
                    name: "デパート"
                    status: 1
                  - facility_category_id: 2
                    name: "ショッピングセンター"
                    status: 1
                  - facility_category_id: 3
                    name: "ホームセンター"
                    status: 1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /owner-industries:
    get:
      tags:
        - Owner Industries
      summary: Get owner industries
      description: Retrieve owner industries from Rakuichi System
      responses:
        '200':
          description: Owner industries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OwnerIndustry'
              example:
                success: true
                data:
                  - owner_industry_id: 1
                    name: "商店街"
                    priority: 100
                    status: 1
                  - owner_industry_id: 2
                    name: "ショッピングセンター"
                    priority: 100
                    status: 1
                  - owner_industry_id: 3
                    name: "ホームセンター"
                    priority: 100
                    status: 1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /taxes:
    get:
      tags:
        - Taxes
      summary: Get tax information
      description: Retrieve tax information from Rakuichi System for a specific date
      parameters:
        - name: filter_date
          in: query
          schema:
            type: string
            format: date
          description: Date to get tax rate for (YYYY-MM-DD). If not provided, uses current date
          example: "2024-01-15"
      responses:
        '200':
          description: Tax information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Tax'
              example:
                success: true
                data:
                  tax_id: 1
                  name: "消費税"
                  rate: 0.1
                  valid_from: "2019-01-01"
                  valid_to: null
        '404':
          description: Tax information not found for the specified date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Tax information not found for the specified date"
                code: "TAX_NOT_FOUND"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

  /admin-accounts:
    get:
      tags:
        - Admin Accounts
      summary: Get admin account information
      description: Retrieve admin account information including email addresses from Rakuichi System
      parameters:
        - name: admin_account_id
          in: query
          schema:
            type: integer
          description: Specific admin account ID to retrieve
          example: 1
        - name: name
          in: query
          schema:
            type: string
          description: Admin account name (partial match)
          example: "管理"
      responses:
        '200':
          description: Admin account information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminAccount'
              example:
                success: true
                data:
                  - admin_account_id: 1
                    email: "admin01@mail.com"
                  - admin_account_id: 2
                    email: "admin02@mail.com"
        '404':
          description: Admin account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Admin account not found"
                code: "ADMIN_ACCOUNT_NOT_FOUND"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Internal server error"
                code: "SERVER_ERROR"

tags:
  - name: Orders
    description: Order management APIs for Rakuichi System integration
  - name: Place Integration
    description: Place data synchronization APIs for Rakuichi System integration
  - name: Holiday Master
    description: Holiday master data APIs for Rakuichi System integration
  - name: Facility Categories
    description: Facility categories APIs for Rakuichi System integration
  - name: Owner Industries
    description: Owner industries APIs for Rakuichi System integration
  - name: Taxes
    description: Tax information APIs for Rakuichi System integration
  - name: Admin Accounts
    description: Admin account information APIs for Rakuichi System integration

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API Key for authentication with Rakuichi System

  schemas:
    OrderDetail:
      type: object
      required:
        - id
        - facility_id
        - facility_name
      properties:
        id:
          type: integer
          description: Order ID
          example: 12345
        facility_id:
          type: integer
          description: Facility ID
          example: 1001
        facility_name:
          type: string
          description: Facility name
          example: "Tokyo Convention Center"
        place:
          type: string
          nullable: true
          description: Place name
          example: "Main Hall A"
        prefectures:
          type: string
          nullable: true
          description: Prefecture/State
          example: "Tokyo"
        ward:
          type: string
          nullable: true
          description: Ward/District
          example: "Chiyoda"
        block_address:
          type: string
          nullable: true
          description: Detailed address
          example: "1-1-1 Marunouchi"
        building:
          type: string
          nullable: true
          description: Building name
          example: "Marunouchi Building"
        breadth:
          type: string
          nullable: true
          description: Size/dimensions
          example: "100m²"
        total_price:
          type: integer
          nullable: true
          description: Total price
          example: 500000
        total_tax_price:
          type: integer
          nullable: true
          description: Total price including tax
          example: 550000
        tax:
          type: integer
          nullable: true
          description: Tax amount
          example: 50000
        user_company_name:
          type: string
          nullable: true
          description: User company name
          example: "ABC Corporation"
        start_date:
          type: string
          format: date
          nullable: true
          description: Start date (YYYY-MM-DD)
          example: "2024-01-15"
        end_date:
          type: string
          format: date
          nullable: true
          description: End date (YYYY-MM-DD)
          example: "2024-01-16"
        commodity:
          type: string
          nullable: true
          description: Commodity type
          example: "Event Equipment"
        commodity_detail:
          type: string
          nullable: true
          description: Commodity details
          example: "Audio system, lighting"
        field_manager_tel:
          type: string
          nullable: true
          description: Field manager telephone
          example: "03-1234-5678"
        number_of_visitors:
          type: integer
          nullable: true
          description: Number of visitors
          example: 100
        visitor:
          type: string
          nullable: true
          description: Visitor information
          example: "General public"
        start_at:
          type: string
          format: time
          nullable: true
          description: Start time (HH:mm:ss)
          example: "09:00:00"
        end_at:
          type: string
          format: time
          nullable: true
          description: End time (HH:mm:ss)
          example: "18:00:00"
        carry_in_time:
          type: string
          nullable: true
          description: Carry-in time
          example: "08:00"
        carry_out_time:
          type: string
          nullable: true
          description: Carry-out time
          example: "19:00"
        carry_car:
          type: string
          nullable: true
          description: Carry vehicle information
          example: "2-ton truck"
        carry_car_remark:
          type: string
          nullable: true
          description: Carry vehicle remarks
          example: "Enter from back gate"
        power:
          type: string
          nullable: true
          description: Power information
          example: "100V, 200V available"
        power_detail:
          type: string
          nullable: true
          description: Power details
          example: "10 outlets available"
        equipment:
          type: string
          nullable: true
          description: Equipment
          example: "Tables, chairs"
        equipment_detail:
          type: string
          nullable: true
          description: Equipment details
          example: "20 tables, 100 chairs"
        equipment_request:
          type: string
          nullable: true
          description: Equipment requests
          example: "Additional lighting needed"
        handout:
          type: string
          nullable: true
          description: Handout materials
          example: "Event brochure"
        shop_guide:
          type: string
          nullable: true
          description: Shop guide information
          example: "Available on request"
        shop_guide_tel:
          type: string
          nullable: true
          description: Shop guide telephone
          example: "03-1234-5679"
        remark:
          type: string
          nullable: true
          description: General remarks
          example: "Special setup required"
        order_status:
          type: object
          nullable: true
          properties:
            remark:
              type: string
              nullable: true
              description: Status remarks
              example: "Order confirmed"
            order_status:
              type: integer
              nullable: true
              description: Order status
              example: 2
        facilities:
          type: object
          nullable: true
          properties:
            owner_no:
              type: string
              nullable: true
              description: Owner number
              example: "OWNER001"

    OrderList:
      type: object
      required:
        - Orders
      properties:
        orders:
          type: array
          description: List of orders
          items:
            type: object
            required:
              - id
              - created_at
              - facility_id
              - facility_name
            properties:
              id:
                type: integer
                description: Order ID
                example: 12345
              created_at:
                type: string
                format: date-time
                description: Order creation date and time
                example: "2024-01-15T10:30:00Z"
              facility_id:
                type: integer
                description: Facility ID
                example: 1001
              facility_name:
                type: string
                description: Facility name
                example: "Tokyo Convention Center"
              place:
                type: string
                nullable: true
                description: Place name
                example: "Main Hall A"
              user_company_name:
                type: string
                nullable: true
                description: User company name
                example: "ABC Corporation"
              commodity:
                type: string
                nullable: true
                description: Commodity type
                example: "Event Equipment"
              admin_account_name:
                type: string
                nullable: true
                description: Admin account name
                example: "Admin User"
              start_date:
                type: string
                format: date
                nullable: true
                description: Start date (YYYY-MM-DD)
                example: "2024-01-15"
              end_date:
                type: string
                format: date
                nullable: true
                description: End date (YYYY-MM-DD)
                example: "2024-01-16"
              order_status:
                type: object
                nullable: true
                properties:
                  order_status:
                    type: integer
                    nullable: true
                    description: Order status
                    example: 2
        pagination:
          type: object
          nullable: true
          description: Pagination information
          properties:
            current_page:
              type: integer
              description: Current page number
              example: 1
            per_page:
              type: integer
              description: Number of items per page
              example: 20
            total:
              type: integer
              description: Total number of items
              example: 2
            total_pages:
              type: integer
              description: Total number of pages
              example: 1
            has_next:
              type: boolean
              description: Whether there is a next page
              example: false
            has_prev:
              type: boolean
              description: Whether there is a previous page
              example: false

    ErrorResponse:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Human-readable error message
          example: "Order not found"
        code:
          type: string
          description: Machine-readable error code for programmatic handling
          example: "ORDER_NOT_FOUND"
        details:
          type: object
          nullable: true
          description: Additional error details (if available)
          properties:
            field:
              type: string
              description: Field that caused the error
            message:
              type: string
              description: Detailed error message
            order_id:
              type: integer
              description: Order ID that was requested (for 404 errors)

    HolidayMaster:
      type: object
      properties:
        holiday_id:
          type: integer
          description: Holiday ID
        holiday_date:
          type: string
          format: date
          description: Holiday date (YYYY-MM-DD)
        holiday_name:
          type: string
          description: Holiday name

    FacilityCategory:
      type: object
      properties:
        facility_category_id:
          type: integer
          description: Facility category ID
        name:
          type: string
          description: Facility category name
        status:
          type: integer
          description: Status (1:active, 2:inactive)

    OwnerIndustry:
      type: object
      properties:
        owner_industry_id:
          type: integer
          description: Owner industry ID
        name:
          type: string
          description: Owner industry name
        priority:
          type: integer
          description: Display priority
        status:
          type: integer
          description: Status (1:active, 2:inactive)

    Tax:
      type: object
      properties:
        tax_id:
          type: integer
          description: Tax ID
        name:
          type: string
          description: Tax name
        rate:
          type: number
          format: float
          description: Tax rate (e.g. 0.10 for 10%)
        valid_from:
          type: string
          format: date
          description: Valid from date (YYYY-MM-DD)
        valid_to:
          type: string
          format: date
          nullable: true
          description: Valid to date (YYYY-MM-DD, nullable)

    AdminAccount:
      type: object
      properties:
        admin_account_id:
          type: integer
          description: Admin account ID
        email:
          type: string
          format: email
          description: Admin email address

    Place:
      type: object
      properties:
        place_id:
          type: integer
          description: Place ID
        facility_id:
          type: integer
          description: Facility ID
        owner_place_id:
          type: integer
          description: Owner place ID
        place:
          type: string
          description: Place name
        owner_no:
          type: string
          nullable: true
          description: Owner number
        breadth:
          type: string
          nullable: true
          description: Size/dimensions
        start_at:
          type: string
          format: time
          nullable: true
          description: Start time (HH:mm:ss)
        end_at:
          type: string
          format: time
          nullable: true
          description: End time (HH:mm:ss)
        inout_door_flag:
          type: integer
          description: Indoor/outdoor flag (0:to be confirmed, 1:indoor, 2:outdoor with roof, 3:outdoor without roof)
        inout_door_comment:
          type: string
          nullable: true
          description: Indoor/outdoor comment
        weekday_sell_price:
          type: integer
          nullable: true
          description: Weekday selling price
        saturday_sell_price:
          type: integer
          nullable: true
          description: Saturday selling price
        holiday_sell_price:
          type: integer
          nullable: true
          description: Holiday selling price
        power_flag:
          type: integer
          description: Power availability flag (0:-, 1:available, 2:not available)
        power_comment:
          type: string
          nullable: true
          description: Power comment
        desk_flag:
          type: integer
          description: Desk availability flag (0:-, 1:available, 2:not available)
        desk_comment:
          type: string
          nullable: true
          description: Desk comment
        chair_flag:
          type: integer
          description: Chair availability flag (0:-, 1:available, 2:not available)
        chair_comment:
          type: string
          nullable: true
          description: Chair comment
        wifi_flag:
          type: integer
          description: WiFi availability flag (0:-, 1:available, 2:not available)
        wifi_comment:
          type: string
          nullable: true
          description: WiFi comment
        food_flag:
          type: integer
          description: Food availability flag (0:-, 1:available, 2:not available)
        food_comment:
          type: string
          nullable: true
          description: Food comment
        ngcommodity_flag:
          type: integer
          description: NG commodity flag (0:not set, 1:available, 2:not available)
        ngcommodity_comment:
          type: string
          nullable: true
          description: NG commodity comment
        comment:
          type: string
          nullable: true
          description: General comment
        caution_comment:
          type: string
          nullable: true
          description: Caution comment
        invalid_week:
          type: string
          nullable: true
          description: Invalid week days
        apply_expired:
          type: string
          nullable: true
          description: Application deadline
        replay:
          type: string
          nullable: true
          description: Reply estimate
        replay_day:
          type: string
          nullable: true
          description: Reply day estimate
        apply_caution_comment:
          type: string
          nullable: true
          description: Application caution comment
        opening_caution_comment:
          type: string
          nullable: true
          description: Opening caution comment
        pre_meeting:
          type: string
          nullable: true
          description: Pre-meeting requirement
        furniture:
          type: string
          nullable: true
          description: Furniture rental
        furniture_remark:
          type: string
          nullable: true
          description: Furniture remark
        carriage:
          type: string
          nullable: true
          description: Carriage rental
        carry_in_time:
          type: string
          nullable: true
          description: Carry-in time
        leaving_time:
          type: string
          nullable: true
          description: Leaving time
        cancel_policy:
          type: string
          nullable: true
          description: Cancellation policy
        memo:
          type: string
          nullable: true
          description: Internal memo (owner use)
        notification:
          type: integer
          description: Availability notification (1:send, 2:don't send)
        notification_from:
          type: integer
          nullable: true
          description: Notification target week FROM
        notification_to:
          type: integer
          nullable: true
          description: Notification target week TO
        owner_account:
          type: integer
          description: Owner account
        created_user:
          type: integer
          description: Created user (authentication ID)
        calendar_last_updated_at:
          type: string
          format: date-time
          description: Calendar last updated timestamp
          example: "2024-01-15T10:30:00Z"
        status:
          type: integer
          description: Status (1:active, 2:inactive)
        is_test:
          type: integer
          description: Test flag (0:production, 1:test)