openapi: 3.0.0
info:
  title: Web Tabs
  description: Web tabs allow you to embed external web pages or applications within Zoho Books. Create custom tabs that load URLs, making it easy to access third-party tools directly from the Zoho Books interface.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: web-tabs
    description: Web Tabs Module
paths:
  /settings/tabs:
    get:
      tags:
        - web-tabs
      operationId: list_web_tabs
      summary: List web tabs
      description: List all the web tabs configured for the organization.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-web-tabs-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - web-tabs
      operationId: create_web_tab
      summary: Create a web tab
      description: Create a new web tab for the organization.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-web-tab-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-web-tab-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /settings/tabs/{webtab_id}:
    get:
      tags:
        - web-tabs
      operationId: get_web_tab
      summary: Get a web tab
      description: Get the details of a specific web tab.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-web-tab-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - web-tabs
      operationId: update_web_tab
      summary: Update a web tab
      description: Update an existing web tab.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-web-tab-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-web-tab-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - web-tabs
      operationId: delete_web_tab
      summary: Delete a web tab
      description: Delete an existing web tab.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-web-tab-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: webtab_id
        in: path
        required: true
        description: Unique identifier of the web tab.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
  /settings/tabs/{webtab_id}/status:
    post:
      tags:
        - web-tabs
      operationId: update_web_tab_status
      summary: Update web tab status
      description: Activate or deactivate a web tab.
      parameters:
        - name: active
          in: query
          description: Set to <code>true</code> to activate or <code>false</code> to deactivate the web tab.
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-web-tab-status-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - name: webtab_id
        in: path
        required: true
        description: Unique identifier of the web tab.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
  /settings/tabs/reorder:
    post:
      tags:
        - web-tabs
      operationId: reorder_web_tabs
      summary: Reorder web tabs
      description: Reorder the display order of web tabs.
      parameters:
        - name: tab_ids
          in: query
          description: Comma-separated list of web tab IDs in the desired order. Maximum 200 IDs.
          required: true
          schema:
            type: string
          example: 982000000567001,982000000567002,982000000567003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reorder-web-tabs-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
components:
  parameters:
    organization_id:
      name: organization_id
      description: ID of the organization
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    web_tab:
      type: object
      properties:
        webtab_id:
          type: string
          description: Unique identifier of the web tab.
          example: '982000000567001'
        name:
          type: string
          description: Name of the web tab.
          example: Analytics Dashboard
        url:
          type: string
          description: URL of the web page to embed.
          example: https://analytics.example.com/dashboard
        order:
          type: integer
          description: Display order of the web tab.
          example: 1
        shared_mode:
          type: string
          description: 'Sharing mode. Allowed Values: <code>all</code>, <code>onlyme</code> and <code>selected</code>.'
          example: all
        portal_webtab:
          type: boolean
          description: Whether this web tab is available in the portal.
          example: false
        is_zoho_url:
          type: boolean
          description: Whether the URL is a Zoho URL.
          example: false
        is_active:
          type: boolean
          description: Whether the web tab is active.
          example: true
    create-web-tab-request:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the web tab.
          example: Analytics Dashboard
        url:
          type: string
          description: URL of the web page to embed. <code>Max-length [500]</code>
          example: https://analytics.example.com/dashboard
        order:
          type: integer
          description: Display order of the web tab.
          example: 1
        shared_mode:
          type: string
          description: 'Sharing mode. Allowed Values: <code>all</code>, <code>onlyme</code> and <code>selected</code>.'
          example: all
        shared_to:
          type: array
          description: List of users/roles to share the web tab with (used when <code>shared_mode</code> is <code>selected</code>).
          items:
            type: object
            properties:
              shared_type:
                type: string
                description: 'Type of sharing. Allowed Values: <code>user</code> or role-based (e.g., <code>books_role</code>).'
                example: user
              shared_id:
                type: integer
                format: int64
                description: ID of the user or role.
              role_name:
                type: string
                description: Name of the role.
              permission:
                type: string
                description: 'Permission level. Allowed Values: <code>read</code>, <code>write</code>, <code>writeonly</code> and <code>none</code>.'
        portal_webtab:
          type: boolean
          description: Whether this web tab should be available in the portal.
          example: false
        is_zoho_url:
          type: boolean
          description: Whether the URL is a Zoho URL.
          example: false
    update-web-tab-request:
      type: object
      properties:
        name:
          type: string
          description: Name of the web tab.
          example: Analytics Dashboard
        url:
          type: string
          description: URL of the web page to embed. <code>Max-length [500]</code>
          example: https://analytics.example.com/dashboard
        order:
          type: integer
          description: Display order of the web tab.
          example: 1
        shared_mode:
          type: string
          description: 'Sharing mode. Allowed Values: <code>all</code>, <code>onlyme</code> and <code>selected</code>.'
          example: all
        shared_to:
          type: array
          description: List of users/roles to share the web tab with (used when <code>shared_mode</code> is <code>selected</code>).
          items:
            type: object
            properties:
              shared_type:
                type: string
                description: 'Type of sharing. Allowed Values: <code>user</code> or role-based (e.g., <code>books_role</code>).'
                example: user
              shared_id:
                type: integer
                format: int64
                description: ID of the user or role.
              role_name:
                type: string
                description: Name of the role.
              permission:
                type: string
                description: 'Permission level. Allowed Values: <code>read</code>, <code>write</code>, <code>writeonly</code> and <code>none</code>.'
        portal_webtab:
          type: boolean
          description: Whether this web tab should be available in the portal.
          example: false
        is_zoho_url:
          type: boolean
          description: Whether the URL is a Zoho URL.
          example: false
    create-web-tab-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The web tab has been created.
        web_tab:
          $ref: '#/components/schemas/web_tab'
    update-web-tab-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The web tab has been updated.
        web_tab:
          $ref: '#/components/schemas/web_tab'
    get-web-tab-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        web_tab:
          $ref: '#/components/schemas/web_tab'
    list-web-tabs-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        web_tabs:
          type: array
          items:
            $ref: '#/components/schemas/web_tab'
    delete-web-tab-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The web tab has been deleted.
    update-web-tab-status-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The web tab status has been updated.
    reorder-web-tabs-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The web tabs have been reordered.
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoBooks.settings.CREATE: Create Settings
            ZohoBooks.settings.UPDATE: Update Settings
            ZohoBooks.settings.READ: Read Settings
            ZohoBooks.settings.DELETE: Delete Settings
