Xentral Tax Rate API

openapi: 3.0.0
info:
  title: Xentral Account Tax Rate API
  version: v0.1
  description: Xentral is an ERP platform.
  contact:
    name: Xentral
    url: https://xentral.com
    email: api@xentral.com
servers:
- url: https://{xentralId}.xentral.biz
  description: Your Xentral Instance
  variables:
    xentralId:
      default: xentral
- url: https://{domain}
  description: Xentral at a custom domain
  variables:
    domain:
      default: xentral.com
security:
- BearerAuth: []
tags:
- name: Tax Rate
  description: Represents a tax rate for a product on given day and for given country
paths:
  /api/v1/taxRates/{countryCode}:
    get:
      tags:
      - Tax Rate
      operationId: taxRate.list
      summary: List tax rates
      description: 'This endpoint returns the tax rate for a given country code. The country code is a two-letter ISO 3166-1 alpha-2 code. The response is a list of applicable tax rates for the given country code.

        To get a more granular response you can use the query parameters to filter the response, for example by product or project.


        The applicable tax rate is determined in the following order:

        1. If a custom tax rate is defined for the product, it is returned.

        2. If a tax rate is defined in the taxRates module for that country, it is returned.

        3. If a tax rate is defined in the taxRates module for the project, or a generic tax Rate without country or project it is returned.

        4. If a tax rate is defined for the applicable project it is returned.

        5. If a tax rate is defined for the system it is returned.

        6. If no tax rate is defined anywhere we will return an empty list.


        To see which step was used to determine the tax rate, the source field is returned in the response.'
      parameters:
      - in: path
        name: countryCode
        required: true
        description: This is the country code for which the tax rates are requested
        schema:
          type: string
        example: DE
      - name: filter
        in: query
        style: deepObject
        schema:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              key:
                type: string
                enum:
                - productId
                - date
                - type
                - projectId
              op:
                type: string
                enum:
                - equals
                - notEquals
                - in
                - notIn
                - exactlyIn
                - allIn
                - allNotIn
                - contains
                - notContains
                - startsWith
                - endsWith
                - greaterThan
                - lessThan
                - is
                - lessThanOrEquals
                - greaterThanOrEquals
              value:
                oneOf:
                - type: string
                  description: Used for the operations 'equals', 'notEquals', 'contains', 'notContains', 'startsWith', 'endsWith' and 'is'.
                  title: String
                - type: array
                  description: Used for the operations 'in', 'notIn', 'exactlyIn', 'allIn' and 'allNotIn'.
                  title: Array
                  items:
                    type: string
      - in: query
        name: page
        required: false
        style: deepObject
        schema:
          type: object
          additionalProperties: false
          required:
          - number
          - size
          properties:
            number:
              type: string
              pattern: \d+
              description: Page number should be an integer greater than or equal to 1
            size:
              type: string
              pattern: \d+
              description: Page size should usually be an integer between 10 and 50.
      responses:
        '200':
          description: Operation completed successfully.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        rate:
                          type: string
                          description: Tax rate value in percent
                          example: Support Request
                        type:
                          type: string
                          description: 'Tax rate type: standard, reduced or custom'
                          example: Support Request
                        date:
                          type: string
                          format: date
                          description: Requested date or current date if no date was specified
                          example: '2023-09-09'
                        name:
                          type: string
                          nullable: true
                          description: Tax rate's designation
                          example: Support Request
                        product:
                          description: Nullable reference to another resource
                          type: object
                          additionalProperties: false
                          nullable: true
                          required:
                          - id
                          properties:
                            id:
                              type: string
                              pattern: \d+
                              example: '17'
                              description: Resource identifier.
                          example:
                            id: '1337'
                        project:
                          description: Nullable reference to another resource
                          type: object
                          additionalProperties: false
                          nullable: true
                          required:
                          - id
                          properties:
                            id:
                              type: string
                              pattern: \d+
                              example: '17'
                              description: Resource identifier.
                          example:
                            id: '1337'
                        source:
                          type: string
                          description: Informs how was the tax rate determined
                          example: Support Request
                  extra:
                    type: object
                    required:
                    - totalCount
                    - page
                    additionalProperties: false
                    x-description-ignore: true
                    properties:
                      totalCount:
                        description: the total count of all items
                        type: integer
                        example: 1
                      page:
                        description: The pagination object containing the current page number and size
                        type: object
                        required:
                        - number
                        - size
                        additionalProperties: false
                        properties:
                          number:
                            description: The current page number
                            type: integer
                            example: 1
                          size:
                            description: The size of the pages
                            type: integer
                            example: 10
                        example:
                          number: 1
                          size: 10
                    example:
                      totalCount: 1
                      page:
                        number: 1
                        size: 10
        '400':
          description: IETF RFC 9457 Problem API compliant response
          content:
            application/problem+json:
              schema:
                oneOf:
                - type: object
                  additionalProperties: false
                  required:
                  - type
                  - title
                  - violations
                  properties:
                    type:
                      type: string
                      enum:
                      - https://api.xentral.biz/problems/request-validation
                    title:
                      type: string
                      minLength: 1
                      example: Request payload validation failed.
                    violations:
                      oneOf:
                      - type: array
                        items:
                          type: object
                          example:
                            username:
                            - This value should not be blank.
                            email:
                            - This value is not a valid email address.
                        description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
                      - type: object
                        example:
                          _:
                          - This value should contain at most `9` elements.
                        description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
                - type: object
                  additionalProperties: false
                  required:
                  - type
                  - title
                  - messages
                  properties:
                    type:
                      type: string
                      enum:
                      - https://api.xentral.biz/problems/generic-validation
                    title:
                      type: string
                      minLength: 1
                    messages:
                      type: array
                      items:
                        type: string
                - type: object
                  additionalProperties: false
                  required:
                  - type
                  - title
                  - messages
                  properties:
                    type:
                      type: string
                      enum:
                      - https://api.xentral.biz/problems/conflict
                    title:
                      type: string
                      minLength: 1
                    messages:
                      type: array
                      items:
                        type: string
                - type: object
                  additionalProperties: false
                  required:
                  - type
                  - title
                  - items
                  properties:
                    type:
                      type: string
                      enum:
                      - https://api.xentral.biz/problems/conflictItems
                    title:
                      type: string
                      minLength: 1
                    items:
                      type: array
                      items:
                        type: object
                        additionalProperties: false
                        required:
                        - id
                        - title
                        - messages
                        properties:
                          id:
                            type: integer
                          title:
                            type: string
                            minLength: 1
                          messages:
                            type: array
                            items:
                              type: string
                - type: object
                  additionalProperties: false
                  required:
                  - type
                  - title
                  - scopes
                  properties:
                    type:
                      type: string
                      enum:
                      - https://developer.xentral.com/reference/problems#token-scopes
                    title:
                      type: string
                      minLength: 1
                    scopes:
                      type: array
                      items:
                        type: string
                - type: object
                  additionalProperties: false
                  required:
                  - type
                  - title
                  - messages
                  properties:
                    type:
                      type: string
                      enum:
                      - https://api.xentral.biz/problems/generic-validation
                    title:
                      type: string
                      minLength: 1
                    messages:
                      type: object
                      additionalProperties:
                        type: array
                        items:
                          type: string
        '401':
          description: Unable to authenticate the client
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message explaining why the request failed.
                    example: 'Missing required scopes: customer:create.'
              example:
                message: 'Missing required scopes: customer:create.'
            text/html:
              schema:
                type: string
                example: Unauthorized
        '403':
          description: Unable to authorize the client
        '406':
          description: Requested resource representation does not exist.
        '429':
          description: Too many API calls made.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained in POST /tokens endpoint or pregenerated in the system.
x-readme:
  samples-languages: []