feat(tax): TAX-1995 Add specs for new TaxZone check endpoint

reference/tax_zone_check.v3.yml

@@ -0,0 +1,187 @@
+openapi: '3.0.0'
+info:
+  title: Tax Zone Check
+  description: Check what tax zone a given address and customer group derives to.
+  termsOfService: 'https://www.bigcommerce.com/terms'
+  contact:
+    name: BigCommerce
+    url: 'https://www.bigcommerce.com'
+    email: [email protected]
+  version: ''
+security:
+  - X-Auth-Token: [ ]
+tags:
+  - name: Tax Zone Check
+servers:
+  - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3'
+    variables:
+      store_hash:
+        default: store_hash
+        description: Permanent ID of the BigCommerce store.
+    description: BigCommerce API Gateway
+paths:
+  "/tax/zonecheck":
+    parameters:
+      - $ref: '#/components/parameters/Accept'
+    post:
+      tags:
+        - Tax Zone Check
+      summary: Check zone given an address.
+      description: Check what tax zone a given address and customer group derives to.
+      operationId: zone-check
+      parameters:
+        - $ref: '#/components/parameters/ContentType'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/ZoneCheck'
+        required: true
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/TaxZone'
+        "422":
+          description: The request body does not meet specifications.
+components:
+  parameters:
+    Accept:
+      name: Accept
+      in: header
+      required: true
+      description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.'
+      schema:
+        type: string
+        default: 'application/json'
+    ContentType:
+      name: Content-Type
+      in: header
+      required: true
+      description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.'
+      schema:
+        type: string
+        default: 'application/json'
+  schemas:
+    ZoneCheck:
+      title: ZoneCheck
+      type: object
+      properties:
+        country_code:
+          type: string
+          example: 'AU'
+          description: Two-letter ISO 3166-1 country code.
+          required: true
+        subdivision_codes:
+          type: string
+          example: 'NSW'
+          description: Three-letter ISO 3166-2 subdivision code.
+          required: false
+        postal_code:
+          type: string
+          example: '2099'
+          description: Postal Code.
+          required: false
+        customer_group_id:
+          type: integer
+          example: 0
+          description: Customer Group Id that a customer is attached to.
+          required: false
+    TaxZone:
+      type: object
+      x-examples: { }
+      properties:
+        id:
+          type: integer
+          description: 'Tax Zone ID. Internal identifier used to get, update, or delete a specific tax zone.'
+          example: 1
+        name:
+          type: string
+          description: The human-readable name for this tax zone. The name displays on the merchant's control panel.
+          example: Australia
+        enabled:
+          type: boolean
+          description: Indicates whether a tax zone is enabled. Tax operations are only for enabled zones.
+          default: true
+        price_display_settings:
+          type: object
+          description: Settings that describe how a store displays prices to shoppers matched with this tax zone.
+          properties:
+            show_inclusive:
+              type: boolean
+              description: Indicates whether to show prices as tax inclusive or tax exclusive to shoppers matched with this tax zone.
+            show_both_on_detail_view:
+              type: boolean
+              description: 'Indicates whether to show both tax inclusive and tax exclusive prices when viewing product detail; for example, on product pages. This view applies to shoppers matched with this tax zone.'
+            show_both_on_list_view:
+              type: boolean
+              description: 'Indicates whether to show both tax inclusive and tax exclusive prices when viewing a list of products; for example, on category and brand pages. This view applies to shoppers matched with this tax zone.'
+        shopper_target_settings:
+          type: object
+          description: Settings that describe which shoppers match this tax zone and help determine the most appropriate target for a shopper. You cannot define shopper target settings for the default tax zone because it must accommodate all shoppers who donʼt qualify for any other zone.
+          properties:
+            locations:
+              type: array
+              description: A tax zone may target shoppers in one or more locations.
+              items:
+                type: object
+                properties:
+                  country_code:
+                    type: string
+                    example: AU
+                    description: Two-letter ISO 3166-1 country code
+                  subdivision_codes:
+                    type: array
+                    example:
+                      - NSW
+                      - QLD
+                    description: Three-letter ISO 3166-2 subdivision code
+                    items:
+                      type: string
+                  postal_codes:
+                    type: array
+                    example:
+                      - '2234'
+                      - '2170'
+                    items:
+                      type: string
+            customer_groups:
+              type: array
+              description: One or more customer groups that a tax zone targets. Empty array if zone applies to all customers.
+              items:
+                type: integer
+  securitySchemes:
+    X-Auth-Token:
+      name: X-Auth-Token
+      description: |-
+        ### OAuth scopes
+
+        | UI Name | Permission | Parameter |
+        |:--------|:-----------|:----------|
+        |  Information & Settings | modify | `store_v2_information` |
+        |  Information & Settings | read-only | `store_v2_information_read_only` |
+
+        ### Authentication header
+
+        | Header | Argument | Description |
+        |:-------|:---------|:------------|
+        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |
+
+        ### Further reading
+
+        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).
+
+        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).
+
+        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).
+      type: apiKey
+      in: header