openapi: 3.0.1
info:
  title: Taxes
  version: 2.10.0
  description: Taxes REST API for tax data management.
  contact:
    name: Jan Terlecki
servers:
  - url: https://tvda-api.platform-test.tradevest.ai
    description: Test
security:
  - Bearer: []
tags:
  - name: TaxInformation
    description: Tax information endpoints
  - name: TaxExemption
    description: Tax exemption endpoints
paths:
  /taxes/tax-information:
    get:
      summary: Get Tax Information
      description: Get data about tax calculations for the given entity in the given tax year.
      operationId: getTaxInformation
      x-operation-group: taxes-query
      x-required-permissions: rs/taxes/read
      tags:
        - TaxInformation
      parameters:
        - $ref: '#/components/parameters/entityId'
        - $ref: '#/components/parameters/entityType'
        - $ref: '#/components/parameters/year'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxInformation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /taxes/tax-exemption-orders:
    get:
      summary: Get Tax Exemption Orders
      description: Get a list of tax exemption orders
      operationId: getTaxExemptionOrders
      x-operation-group: taxes-query
      x-required-permissions: rs/taxes/read
      tags:
        - TaxExemption
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/taxExemptionOrderIdQuery'
        - $ref: '#/components/parameters/entityIdOptional'
        - $ref: '#/components/parameters/taxExemptionOrderStatus'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxExemptionOrders'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    post:
      summary: Create Tax Exemption Order
      description: Create a new tax exemption order for the given entity.
      operationId: createTaxExemptionOrder
      x-operation-group: taxes-command
      x-required-permissions: rs/taxes/write
      tags:
        - TaxExemption
      parameters:
        - $ref: '#/components/parameters/requestorId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxExemptionOrderData'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTaxExemptionOrderResult'
  /taxes/tax-exemption-orders/{taxExemptionOrderId}:
    parameters:
      - $ref: '#/components/parameters/taxExemptionOrderIdPath'
    get:
      summary: Get Tax Exemption Order
      operationId: get-tax-exemption-order
      x-operation-group: taxes-query
      x-required-permissions: rs/taxes/read
      description: Get tax exemption order
      tags:
        - TaxExemption
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxExemptionOrder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    patch:
      summary: Update Tax Exemption Order
      operationId: update-tax-exemption-order
      x-operation-group: taxes-command
      x-required-permissions: rs/taxes/write
      description: Update tax exemption order
      tags:
        - TaxExemption
      parameters:
        - $ref: '#/components/parameters/requestorId'
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxExemptionOrderUpdate'
components:
  schemas:
    TaxInformation:
      title: TaxInformation
      type: object
      properties:
        taxYear:
          type: integer
          description: Calendar year of the tax year
        lossPotEquities:
          type: number
          format: decimal
          description: Balance of the STOCK loss pot
        lossPotGeneral:
          type: number
          format: decimal
          description: Balance of the OTHER (general) loss pot
        incomeCoveredEquities:
          type: number
          format: decimal
          description: Income covered by losses from the STOCK loss pot in this tax year
        incomeCoveredGeneral:
          type: number
          format: decimal
          description: Income covered by losses from the OTHER loss pot in this tax year
        usedFsa:
          type: number
          format: decimal
          description: Income covered by the FSA (Saver's Allowance) in this tax year
        withheldCapitalGainsTax:
          type: number
          format: decimal
          description: Total German capital income tax calculated for the taxpayer in this tax year
        withheldSolidarityTax:
          type: number
          format: decimal
          description: Total German solidarity surcharge tax calculated for the taxpayer in this tax year
        withheldChurchTax:
          type: number
          format: decimal
          description: Total German church tax calculated for the taxpayer in this tax year
        creditedForeignWithholdingTax:
          type: number
          format: decimal
          description: Total foreign tax credited for the taxpayer in this tax year
      required:
        - taxYear
        - lossPotEquities
        - lossPotGeneral
        - incomeCoveredEquities
        - incomeCoveredGeneral
        - usedFsa
        - withheldCapitalGainsTax
        - withheldSolidarityTax
        - withheldChurchTax
        - creditedForeignWithholdingTax
    TaxExemptionOrder:
      type: object
      required:
        - createdOn
        - entityId
        - entityType
        - fsaAmount
        - fsaType
        - modifiedOn
        - status
        - taxExemptionOrderId
      properties:
        taxExemptionOrderId:
          type: string
          format: uuid
          description: Unique tax exemption order identification in UUID format
        status:
          $ref: '#/components/schemas/TaxExemptionOrderStatusEnum'
        createdOn:
          type: string
          format: date-time
          description: The date on which the tax exemption order was created
        modifiedOn:
          type: string
          format: date-time
          description: The date on which the tax exemption order was last modified
        entityId:
          type: string
          format: uuid
          description: Unique entity identification in UUID format
        entityType:
          $ref: '#/components/schemas/EntityTypeEnum'
        fsaType:
          $ref: '#/components/schemas/FsaTypeEnum'
        fsaAmount:
          type: number
          format: decimal
          description: The amount to allocate for FSA (must be positive)
        fsaValidFrom:
          type: string
          format: date
          description: Date from which the allocation becomes valid (optional, it will be January 1st if not provided)
        fsaValidUntil:
          type: string
          format: date
          description: Date until which the allocation is valid (optional, must be December 31st if provided)
      title: TaxExemptionOrder
    TaxExemptionOrderData:
      title: TaxExemptionOrderData
      type: object
      properties:
        entityId:
          type: string
          format: uuid
          description: Unique entity identification in UUID format
        entityType:
          $ref: '#/components/schemas/EntityTypeEnum'
        fsaType:
          $ref: '#/components/schemas/FsaTypeEnum'
        fsaAmount:
          type: number
          format: decimal
          description: The amount to allocate for FSA (must be positive)
        fsaValidFrom:
          type: string
          format: date
          description: Date from which the allocation becomes valid (optional, it will be January 1st if not provided)
        fsaValidUntil:
          type: string
          format: date
          description: Date until which the allocation is valid (optional, must be December 31st if provided)
      required:
        - entityId
        - entityType
        - fsaType
        - fsaAmount
    TaxExemptionOrders:
      title: TaxExemptionOrders
      type: object
      properties:
        data:
          type: array
          description: Array of tax exemption orders
          items:
            $ref: '#/components/schemas/TaxExemptionOrder'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    CreateTaxExemptionOrderResult:
      title: CreateTaxExemptionOrderResult
      type: object
      properties:
        taxExemptionOrderId:
          type: string
          format: uuid
          description: Unique tax exemption order identification in UUID format
      required:
        - taxExemptionOrderId
    TaxExemptionOrderUpdate:
      title: TaxExemptionOrderUpdate
      type: object
      properties:
        fsaAmount:
          type: number
          format: decimal
          description: The amount to allocate for FSA (must be positive)
        fsaValidUntil:
          type: string
          format: date
          description: Date until which the allocation is valid (optional, must be December 31st if provided)
    EntityTypeEnum:
      title: EntityTypeEnum
      type: string
      enum:
        - NATURAL_PERSON
        - LEGAL_ENTITY
        - JOINT_PERSON
        - BENEFICIAL_OWNER
        - LEGAL_REPRESENTATIVE
      description: Type of the entity.
    ErrorDetailsExplanation:
      title: ErrorDetailsExplanation
      type: object
      properties:
        code:
          type: string
          maxLength: 255
        parameter:
          type: string
        message:
          type: string
      required:
        - code
        - message
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        field:
          type: string
          maxLength: 255
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailsExplanation'
      required:
        - field
    ErrorMessage:
      title: ErrorMessage
      type: object
      properties:
        message:
          type: string
        responseType:
          type: string
        validationString:
          minLength: 1
          type: string
        requestId:
          type: string
        errorCode:
          type: string
          maxLength: 255
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
      required:
        - message
        - responseType
        - requestId
    TaxExemptionOrderStatusEnum:
      title: TaxExemptionOrderStatusEnum
      type: string
      description: The status of the tax exemption order
      enum:
        - RECEIVED
        - INVALID
        - ACTIVE
        - INACTIVE
    FsaTypeEnum:
      title: FsaTypeEnum
      type: string
      description: The type of the fsa
      enum:
        - INDIVIDUAL
        - JOINT
    Pagination:
      title: Pagination
      type: object
      properties:
        cursor:
          type: string
          description: String value used for pagination, which should be set in next page request.
        limit:
          type: integer
          description: Maximum number of returned items
      required:
        - cursor
        - limit
  parameters:
    entityId:
      schema:
        type: string
        format: uuid
      name: entityId
      in: query
      required: true
      description: Unique entity identification in UUID format
    entityIdOptional:
      schema:
        type: string
        format: uuid
      name: entityId
      in: query
      description: Unique entity identification in UUID format
    entityType:
      schema:
        $ref: '#/components/schemas/EntityTypeEnum'
      name: entityType
      in: query
      required: true
      description: Type of the entity
    year:
      schema:
        type: integer
        minimum: 1900
        maximum: 2100
      name: year
      in: query
      required: true
      description: Calendar year of the tax year
    cursor:
      schema:
        type: string
      in: query
      name: cursor
      description: String value used for pagination
    limit:
      schema:
        type: integer
        default: 20
        minimum: 1
      in: query
      name: limit
      description: Maximum number of items to return
      required: true
    taxExemptionOrderIdQuery:
      schema:
        type: string
        format: uuid
      in: query
      name: taxExemptionOrderId
      description: Tax exemption order ID
    taxExemptionOrderIdPath:
      schema:
        type: string
        format: uuid
      name: taxExemptionOrderId
      in: path
      required: true
      description: Tax exemption order ID
    taxExemptionOrderStatus:
      schema:
        $ref: '#/components/schemas/TaxExemptionOrderStatusEnum'
      in: query
      name: status
      description: Tax exemption order status
    requestorId:
      schema:
        type: string
        format: uuid
      name: Requestor-ID
      in: header
      required: true
      description: Unique requestor identification in UUID format
      x-requestor-id: true
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://tvdcustomauthdomain.auth.eu-central-1.amazoncognito.com/oauth2/token
          scopes: {}
x-tagGroups:
  - name: Tax Information
    tags:
      - TaxInformation
  - name: Tax Exemption
    tags:
      - TaxExemption
