Emporix Taxes API

openapi: 3.2.0
info:
  title: Emporix Taxes API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Taxes across 2 of this provider''s published API definitions: emporix-tax-service-openapi.yml, emporix-tax-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Taxes
paths:
  /tax/{tenant}/taxes:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    post:
      summary: Creating a new tax configuration
      description: Creates a new tax configuration.
      security:
      - OAuth2:
        - tax.tax_manage
      parameters:
      - $ref: '#/components/parameters/trait_contentLanguage_header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/taxCreation'
            examples:
              Tax configuration with a map of localized attributes:
                value:
                  location:
                    countryCode: DE
                  taxClasses:
                  - code: STANDARD
                    name:
                      en: Standard
                    order: 0
                    rate: 19
                    isDefault: true
                  - code: REDUCED
                    name:
                      en: Reduced
                    order: 1
                    rate: 7
                  - code: ZERO
                    name:
                      en: Zero
                    order: 2
                    rate: 0
              Tax configuration with localized attributes:
                value:
                  location:
                    countryCode: DE
                  taxClasses:
                  - code: STANDARD
                    name: Standard
                    order: 0
                    rate: 19
                    isDefault: true
                  - code: REDUCED
                    name: Reduced
                    order: 1
                    rate: 7
                  - code: ZERO
                    name: Zero
                    order: 2
                    rate: 0
        description: ''
      responses:
        '201':
          description: The request was successful. The tax configuration has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taxCreationResponse'
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '409':
          $ref: '#/components/responses/Conflict_409'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      operationId: POST-tax-create-configuration
      tags:
      - Taxes
    get:
      summary: Retrieving all tax configurations
      description: Retrieves all tax configurations assigned to the tenant. You can filter the results with query parameters.
      security:
      - OAuth2:
        - tax.tax_read
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguageV2_header'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_XTotalCount_header'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_name'
      - $ref: '#/components/parameters/trait_rate_query_param'
      - $ref: '#/components/parameters/trait_country_code_query_param'
      - $ref: '#/components/parameters/trait_tax_class_code_query_param'
      - $ref: '#/components/parameters/trait_description_query_param'
      responses:
        '200':
          description: The request was successful. A list of tax configurations is returned.
          content:
            application/json:
              examples:
                Tax configurations with a map of localized attributes:
                  value:
                  - location:
                      countryCode: DE
                    taxClasses:
                    - code: STANDARD
                      name:
                        en: Standard
                      order: 0
                      rate: 19
                      isDefault: true
                    - code: REDUCED
                      name:
                        en: Reduced
                      order: 1
                      rate: 7
                    - code: ZERO
                      name:
                        en: Zero
                      order: 2
                      rate: 0
                    metadata:
                      version: 1
                      createdAt: '2022-03-31T09:52:15.423Z'
                      modifiedAt: '2022-03-31T09:53:25.464Z'
                  - location:
                      countryCode: PL
                    taxClasses:
                    - code: STANDARD
                      name:
                        en: Standard
                      order: 0
                      rate: 23
                    - code: REDUCED_8
                      name:
                        en: Reduced
                      order: 1
                      rate: 8
                      isDefault: true
                    - code: REDUCED_5
                      name:
                        en: Reduced (Food)
                      order: 2
                      rate: 5
                    - code: ZERO
                      name:
                        en: Zero
                      order: 3
                      rate: 0
                    metadata:
                      version: 2
                      createdAt: '2022-03-31T09:52:15.423Z'
                      modifiedAt: '2022-03-31T09:53:25.464Z'
                Tax configurations with localized attributes:
                  value:
                  - location:
                      countryCode: DE
                    taxClasses:
                    - code: STANDARD
                      name: Standard
                      order: 0
                      rate: 19
                      isDefault: true
                    - code: REDUCED
                      name: Reduced
                      order: 1
                      rate: 7
                    - code: ZERO
                      name: Zero
                      order: 2
                      rate: 0
                  - location:
                      countryCode: PL
                    taxClasses:
                    - code: STANDARD
                      name: Standard
                      order: 0
                      rate: 23
                    - code: REDUCED_8
                      name: Reduced
                      order: 1
                      rate: 8
                    - code: REDUCED_5
                      name: Reduced (Food)
                      order: 2
                      rate: 5
                      isDefault: true
                    - code: ZERO
                      name: Zero
                      order: 3
                      rate: 0
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/taxRetrieval'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      tags:
      - Taxes
      operationId: GET-tax-list-configurations
    servers:
    - url: https://api.emporix.io
  /tax/{tenant}/taxes/{locationCode}:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    - schema:
        type: string
      name: locationCode
      in: path
      required: true
      description: Location country code, defined when the tax configuration is created.
    get:
      summary: Retrieving a tax configuration
      description: Retrieves a tax configuration for a specified location.
      security:
      - OAuth2:
        - tax.tax_read
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguageV2_header'
      responses:
        '200':
          description: The request was successful. The tax configuration is returned.
          content:
            application/json:
              examples:
                Tax configuration with a map of localized attributes:
                  value:
                    location:
                      countryCode: DE
                    taxClasses:
                    - code: STANDARD
                      name:
                        en: Standard
                      order: 0
                      rate: 19
                      isDefault: true
                    - code: REDUCED
                      name:
                        en: Reduced
                      order: 1
                      rate: 7
                    - code: ZERO
                      name:
                        en: Zero
                      order: 2
                      rate: 0
                    metadata:
                      version: 2
                      createdAt: '2022-03-31T09:52:15.423Z'
                      modifiedAt: '2022-03-31T09:53:25.464Z'
                Tax configuration with localized attributes:
                  value:
                    location:
                      countryCode: DE
                    taxClasses:
                    - code: STANDARD
                      name: Standard
                      order: 0
                      rate: 19
                      isDefault: true
                    - code: REDUCED
                      name: Reduced
                      order: 1
                      rate: 7
                    - code: ZERO
                      name: Zero
                      order: 2
                      rate: 0
                    metadata:
                      version: 2
                      createdAt: '2022-03-31T09:52:15.423Z'
                      modifiedAt: '2022-03-31T09:53:25.464Z'
              schema:
                $ref: '#/components/schemas/taxRetrieval'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      tags:
      - Taxes
      operationId: GET-tax-retrieve-configuration-by-location
    put:
      summary: Updating a tax configuration
      description: 'Updates a tax configuration based on the specified location code.


        **Note**: The tax configuration''s identifier - the country code - is immutable and cannot be changed using this endpoint.'
      security:
      - OAuth2:
        - tax.tax_manage
      parameters:
      - $ref: '#/components/parameters/trait_contentLanguage_header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/taxUpdate'
            examples:
              Tax configuration with a map of localized attributes:
                value:
                  location:
                    countryCode: DE
                  taxClasses:
                  - code: STANDARD
                    name:
                      en: Standard
                    order: 0
                    rate: 19
                    isDefault: true
                  - code: REDUCED
                    name:
                      en: Reduced
                    order: 1
                    rate: 7
                  - code: ZERO
                    name:
                      en: Zero
                    order: 2
                    rate: 0
                  metadata:
                    version: 1
              Tax configuration with localized attributes:
                value:
                  location:
                    countryCode: DE
                  taxClasses:
                  - code: STANDARD
                    name: Standard
                    order: 0
                    rate: 19
                    isDefault: true
                  - code: REDUCED
                    name: Reduced
                    order: 1
                    rate: 7
                  - code: ZERO
                    name: Zero
                    order: 2
                    rate: 0
                  metadata:
                    version: 1
                    createdAt: '2022-03-31T09:52:15.423Z'
                    modifiedAt: '2022-03-31T09:53:25.464Z'
      responses:
        '204':
          description: The request was successful. The tax configuration has been updated.
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
        '409':
          $ref: '#/components/responses/Conflict_409'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      tags:
      - Taxes
      operationId: PUT-tax-update-configuration-by-location
    delete:
      summary: Deleting a tax configuration
      description: Deletes a tax configuration based on the specified location code.
      security:
      - OAuth2:
        - tax.tax_manage
      responses:
        '204':
          description: The request was successful. The tax configuration has been deleted.
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      tags:
      - Taxes
      operationId: DELETE-tax-remove-configuration-by-location
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    taxCreation:
      title: taxCreation
      type: object
      description: 'Tax configuration for a specified location. It consists of a country code and a list of tax classes applicable in that country.  '
      properties:
        location:
          $ref: '#/components/schemas/location'
        taxClasses:
          type: array
          description: List of tax classes applicable in the specified country.
          items:
            $ref: '#/components/schemas/taxClass'
      required:
      - location
      - taxClasses
    metadata:
      type: object
      properties:
        createdAt:
          description: Date and time when the object was created.
          type: string
          format: date-time
        modifiedAt:
          description: Date and time when the object was last modified.
          type: string
          format: date-time
        version:
          minimum: 1
          type: integer
          description: Version of the object.
    taxUpdate:
      title: taxUpdate
      allOf:
      - $ref: '#/components/schemas/taxCreation'
      - type: object
        properties:
          metadata:
            $ref: '#/components/schemas/metadata'
        required:
        - metadata
    taxCreationResponse:
      title: taxCreationResponse
      type: object
      description: ''
      properties:
        locationCode:
          type: string
          description: Code of country for which the tax configuration has been created.
    errorMessage:
      title: error
      description: Schema for API specified errors.
      type: object
      properties:
        taxConfigurationCode:
          type: string
          description: link to documentation to investigate further and finding support
        code:
          description: classification of the error type, lower case with underscore eg validation_failure
          type: integer
        status:
          description: original HTTP error code, should be consistent with the response HTTP code
          type: string
        message:
          description: descriptive error message for debugging
          type: string
        details:
          description: list of problems causing this error
          type: array
          items:
            title: errorDetail
            description: schema for specific error cause
            type: string
      required:
      - code
      - status
    taxClass:
      title: taxClass
      type: object
      description: 'Single tax class. '
      properties:
        code:
          type: string
          description: Unique tax class code.
        name:
          description: 'Tax class name.


            * If the `Content-Language` header is set to `*`, then the name should be provided as a map of translations, where each key is a language code and the value is the name in its respective language.

            * If the `Content-Language` header is set to a specific language, the name should be provided as a string.

            * If the `Content-Language` header is empty, the endpoint will asume that the name is provided in the default language defined in the Configuration Service.


            **Note**: You can provide the names only in languages defined in the Configuration Service. In case the name is provided in a language that is not defined in the Configuration Service, the request will be rejected.'
          oneOf:
          - type: object
            additionalProperties:
              type: string
          - type: string
        description:
          description: 'Tax class description.


            * If the `Content-Language` header is set to `*`, then the description should be provided as a map of translations, where each key is a language code and the value is the description in its respective language.

            * If the `Content-Language` header is set to a specific language, the description should be provided as a string.

            * If the `Content-Language` header is empty, the endpoint will asume that the description is provided in the default language defined in the Configuration Service.


            **Note**: You can provide the descriptions only in languages defined in the Configuration Service. In case the description is provided in a language that is not defined in the Configuration Service, the request will be rejected.'
          oneOf:
          - type: object
            additionalProperties:
              type: string
          - type: string
        order:
          type: integer
          description: Number indicating the position on the tax class list. Tax classes in a configuration are sorted based on their `order` values in ascending order.
        rate:
          type: number
          description: 'Tax rate, expressed as a number.


            For example, if the tax rate is 23%, this field should be set to `23`.'
        isDefault:
          type: boolean
          description: Indicates that the tax class is a default tax class for the tax configuration. Only one tax class can be marked as a default for a particular tax configuration.
      required:
      - code
      - name
      - rate
    taxRetrieval:
      title: taxRetrieval
      type: object
      description: 'Tax configuration for a specified location. It consists of a country code and a list of tax classes applicable in that country.  '
      properties:
        locationCode:
          type: string
        location:
          $ref: '#/components/schemas/location'
        taxClasses:
          type: array
          description: List of tax classes applicable in the specified country.
          items:
            $ref: '#/components/schemas/taxClass'
        metadata:
          $ref: '#/components/schemas/metadata'
    location:
      type: object
      description: ''
      properties:
        countryCode:
          type: string
          description: Code of the country for which the tax classes are specified, as defined in the Country Service.
      required:
      - countryCode
  parameters:
    trait_description_query_param:
      name: description
      in: query
      required: false
      schema:
        type: string
      description: "Tax class descriptions. When specified, only tax configurations containing the specified tax class descriptions will be returned.\n\n**Important**: See how the `Accept-Language` header influences this parameter:\n  * If The `Accept-Language` header is set to `*`, you need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `*` and you want to find English descriptions containing the word \"Fruit\", this parameter should be set to \"description.en=Fruit\"\n\n  * If the `Accept-Language` header is set to a particular language or not specified, you do not need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `en` and you want to find descriptions containing the word \"Fruit\", this parameter should be set to \"description=Fruit\"\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-sensitive.\n"
    trait_paged_pageNumber:
      name: pageNumber
      in: query
      description: 'Page number to be retrieved. The number of the first page is 1.


        **Note:** If the `pageNumber` parameter is passed, size of the pages must be specified in the `pageSize` parameter.'
      schema:
        default: 1
        minimum: 1
        type: integer
    trait_contentLanguage_header:
      in: header
      schema:
        type: string
      name: Content-Language
      required: true
      description: 'Language in which localized fields in the request body are provided.


        * If the `Content-Language` header is set to `*`, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the `Content-Language` header is set to a specific language, the localized fields should be provided as strings.

        * If the `Content-Language` header is empty, the endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.


        **Note**: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

        '
    trait_XTotalCount_header:
      in: header
      name: X-Total-Count
      required: false
      description: Flag indicating whether the total number of retrieved items should be returned.
      schema:
        default: false
        type: boolean
    trait_name:
      name: name
      in: query
      required: false
      schema:
        type: string
      description: "Tax class names. When specified, only tax configurations containing the specified tax class names will be returned.\n\n**Important**: See how the `Accept-Language` header influences this parameter:\n  * If The `Accept-Language` header is set to `*`, you need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `*` and you want to find English names containing the word \"Reduced\", this parameter should be set to \"name.en=Reduced\"\n\n  * If the `Accept-Language` header is set to a particular language or not specified, you do not need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `en` and you want to find names containing the word \"Reduced\", this parameter should be set to \"name=Reduced\"\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-sensitive.\n"
    trait_country_code_query_param:
      name: countryCode
      in: query
      required: false
      schema:
        type: string
      description: 'Three-letter country codes, as defined in the Country Service. When specified, only tax configurations defined for the specified countries will be returned.


        **Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-sensitive.

        '
    trait_rate_query_param:
      name: rate
      in: query
      required: false
      schema:
        type: string
      description: 'Tax class rates, expressed as numbers. When specified, only tax configurations containing the specified tax class rates will be returned.


        **Note**: When filtering the results with this field, the `equals` operator is used.

        '
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: Number of items to be retrieved per page.
      schema:
        default: 60
        minimum: 1
        type: integer
    trait_tax_class_code_query_param:
      name: taxClassCode
      in: query
      required: false
      schema:
        type: string
      description: 'Tax class codes. When specified, only tax configurations containing the specified tax class codes will be returned.


        **Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-sensitive.

        '
    trait_sort:
      in: query
      name: sort
      required: false
      description: "List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.\n\nPossible values:\n* `{fieldName}`\n* `{fieldName:asc`\n* `{fieldName}:desc`\n\n**Note:** If you want to sort the results by localized properties, the possible values are:\n  * `{fieldName}.{language}`\n  * `{fieldName}.{language}:asc`\n  * `{fieldName}.{language}:desc`\n\nIf the sorting direction is not specified, the fields are sorted in ascending order.\n\nPossible {fieldName} values are:\n  * `name`\n  * `description`\n  * `countryCode`\n  * `taxClassCode`\n  * `rate`"
      schema:
        type: string
        example: name,taxClassCode:desc
    trait_acceptLanguageV2_header:
      in: header
      name: Accept-Language
      required: false
      description: 'List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


        * If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.

        * If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

        '
      schema:
        type: string
        example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
    trait_tenant:
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant name.


        **Note**: The tenant should always be written in lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
  responses:
    BadRequest_400:
      description: Request was syntactically incorrect. Details will be provided in the response payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequest400_AmbiguousTenant'
    NotFound_404:
      description: Resource has not been found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFound404_TaxNotFound'
    InternalServiceError_500:
      description: Internal Service Error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            InternalServiceErrorExample:
              value:
                code: 500
                status: Internal Service Error
                message: A server-side exception occurred that prevented the system from correctly returning the result.
    Forbidden_403:
      description: Given authorization scopes are not sufficient and do not match scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            ForbiddenExample:
              value:
                code: 403
                status: Forbidden
                message: The access to the requested resource has been forbidden by the server.
    Unauthorized_401:
      description: Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            UnauthorizedExample:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            AccessTokenExpiredExample:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    Conflict_409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            ConflictExample:
              value:
                code: 409
                status: Conflict
                message: The object that you are trying to update has already changed. Please refresh and try again!
  examples:
    NotFound404_TaxNotFound:
      value:
        code: 404
        status: Not Found
        message: The tax was not found for this code
    BadRequest400_AmbiguousTenant:
      value:
        code: 400
        status: Bad Request
        message: Tenant in the header is not matching with the one provided in the URI.
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            tax.tax_manage: Needed to create, update, and delete tax configurations.
            tax.tax_read: Needed to retrieve tax configurations.
x-refined-from:
- emporix-tax-service-openapi.yml
- emporix-tax-service-openapi.yml