Visma Vat API

openapi: 3.2.0
info:
  title: Visma.net ERP Vat API
  version: v1
servers:
- url: https://api.finance.visma.net
tags:
- name: Vat
paths:
  /v1/vat/{vatId}:
    get:
      tags:
      - Vat
      summary: Get a specific Vat - TX205000
      operationId: Vat_GetVatByvatId
      parameters:
      - name: vatId
        in: path
        description: Mandatory. Value for VatID to be looked for.
        required: true
        schema:
          type: string
      - name: includeVatCategoryLines
        in: query
        description: Optional. If true, each VAT category in the response also includes its category lines (vatCategoryLines). Loading these requires extra queries, so it is off by default. Default is false.
        schema:
          type: boolean
      - name: erp-api-background
        in: header
        description: 'Accepts the request and queues it to be executed in the background by our least busy worker. Responds with 202 Accepted and a document containing a JobId reference and details state location.

          Supported values:

          * a URL: when the background operation is finished, a notification will be posted to the URL with a document containing a reference id, status code and a details state location.

          * "none" (without quotes): Fire and forget; no notification will be sent when background operation is finished.

          * "subscription[:<name_1>=<value_1>,..,<name_n>=<value_n>]" (without quotes): when the background operation is finsihed, a notification is posted to the Webhook subscription set up in Developer Portal for your integration client.

          Optionally a set of name-value pairs can be added. These will be sent as headers in the POST request to the Webhook subscription''s url.


          To find status and details of a background-api operation, GET .. v1/background/{id}. To get the response payload of a background-api operation, if any, GET .. v1/background/{id}/content'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VatInformationDto'
            text/json:
              schema:
                $ref: '#/components/schemas/VatInformationDto'
        '202':
          description: Server accepted and queued the request for background execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
            text/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
      security:
      - interactiveapi: []
  /v1/vat:
    get:
      tags:
      - Vat
      summary: Get a range of Vats - ScreenId=TX205000
      operationId: Vat_GetAllVats
      parameters:
      - name: includeVatCategoryLines
        in: query
        description: Optional. If true, each VAT category in the response also includes its category lines (vatCategoryLines), scoped to the VAT of that row. Loading these requires extra queries, so it is off by default. Default is false.
        schema:
          type: boolean
      - name: numberToRead
        in: query
        description: This field has been deprecated and will be removed in future versions.
        schema:
          type: integer
          format: int32
      - name: skipRecords
        in: query
        description: This field has been deprecated and will be removed in future versions.
        schema:
          type: integer
          format: int32
      - name: lastModifiedDateTime
        in: query
        description: 'This value, generated by the system, indicates the last time the record was modified. Use it to retrieve all records that have been modified since that time, up to the present.


          Accepted format:

          * ```yyyy-MM-dd```

          * ```yyyy-MM-dd HH:mm:ss```

          * ```yyyy-MM-dd HH:mm:ss.FFF```

          * ```yyyy-MM-ddTHH:mm:ss```

          * ```yyyy-MM-ddTHH:mm:ss.FFF```


          _Note:_ __LastModifiedDateTime__ and __LastModifiedDateTimeCondition__ are __mutually inclusive__.'
        schema:
          type: string
      - name: lastModifiedDateTimeCondition
        in: query
        description: 'This value represents the condition to be applied when retrieving records.


          Accepted values (without the single quotes):

          * ''&gt;'' for greater than

          * ''&lt;'' for less than

          * ''&gt;='' for greater than or equal

          * ''&lt;='' for less than or equal


          _Note:_ __LastModifiedDateTime__ and __LastModifiedDateTimeCondition__ are __mutually inclusive__.'
        schema:
          type: string
      - name: erp-api-background
        in: header
        description: 'Accepts the request and queues it to be executed in the background by our least busy worker. Responds with 202 Accepted and a document containing a JobId reference and details state location.

          Supported values:

          * a URL: when the background operation is finished, a notification will be posted to the URL with a document containing a reference id, status code and a details state location.

          * "none" (without quotes): Fire and forget; no notification will be sent when background operation is finished.

          * "subscription[:<name_1>=<value_1>,..,<name_n>=<value_n>]" (without quotes): when the background operation is finsihed, a notification is posted to the Webhook subscription set up in Developer Portal for your integration client.

          Optionally a set of name-value pairs can be added. These will be sent as headers in the POST request to the Webhook subscription''s url.


          To find status and details of a background-api operation, GET .. v1/background/{id}. To get the response payload of a background-api operation, if any, GET .. v1/background/{id}/content'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VatInformationDto'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VatInformationDto'
        '202':
          description: Server accepted and queued the request for background execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
            text/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
      security:
      - interactiveapi: []
  /v1/vat/{vendorCd}/{taxPeriodId}/{revisionId}:
    put:
      tags:
      - Vat
      summary: Update vat header note
      operationId: Vat_PutVatHeaderNoteByvendorCdtaxPeriodIdrevisionId
      parameters:
      - name: vendorCd
        in: path
        description: Identifies the tax agency.
        required: true
        schema:
          type: string
      - name: taxPeriodId
        in: path
        description: Identifies the tax period.
        required: true
        schema:
          type: string
      - name: revisionId
        in: path
        description: Identifies the tax revision.
        required: true
        schema:
          type: integer
          format: int32
      - name: erp-api-background
        in: header
        description: 'Accepts the request and queues it to be executed in the background by our least busy worker. Responds with 202 Accepted and a document containing a JobId reference and details state location.

          Supported values:

          * a URL: when the background operation is finished, a notification will be posted to the URL with a document containing a reference id, status code and a details state location.

          * "none" (without quotes): Fire and forget; no notification will be sent when background operation is finished.

          * "subscription[:<name_1>=<value_1>,..,<name_n>=<value_n>]" (without quotes): when the background operation is finsihed, a notification is posted to the Webhook subscription set up in Developer Portal for your integration client.

          Optionally a set of name-value pairs can be added. These will be sent as headers in the POST request to the Webhook subscription''s url.


          To find status and details of a background-api operation, GET .. v1/background/{id}. To get the response payload of a background-api operation, if any, GET .. v1/background/{id}/content'
        schema:
          type: string
      requestBody:
        description: Defines the note for the vat header to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          text/xml:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
        required: true
        x-bodyName: noteDto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
            text/json:
              schema:
                type: object
        '202':
          description: Server accepted and queued the request for background execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
            text/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
      security:
      - interactiveapi: []
  /v1/vat/{vendorCd}/{taxPeriodId}/{revisionId}/{lineNumber}:
    put:
      tags:
      - Vat
      summary: Vat put vat line note byvendor cdtax period idrevision idline number
      operationId: Vat_PutVatLineNoteByvendorCdtaxPeriodIdrevisionIdlineNumber
      parameters:
      - name: vendorCd
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: taxPeriodId
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: revisionId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          format: int32
      - name: lineNumber
        in: path
        description: ''
        required: true
        schema:
          type: integer
          format: int32
      - name: erp-api-background
        in: header
        description: 'Accepts the request and queues it to be executed in the background by our least busy worker. Responds with 202 Accepted and a document containing a JobId reference and details state location.

          Supported values:

          * a URL: when the background operation is finished, a notification will be posted to the URL with a document containing a reference id, status code and a details state location.

          * "none" (without quotes): Fire and forget; no notification will be sent when background operation is finished.

          * "subscription[:<name_1>=<value_1>,..,<name_n>=<value_n>]" (without quotes): when the background operation is finsihed, a notification is posted to the Webhook subscription set up in Developer Portal for your integration client.

          Optionally a set of name-value pairs can be added. These will be sent as headers in the POST request to the Webhook subscription''s url.


          To find status and details of a background-api operation, GET .. v1/background/{id}. To get the response payload of a background-api operation, if any, GET .. v1/background/{id}/content'
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          text/xml:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
        required: true
        x-bodyName: noteDto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
            text/json:
              schema:
                type: object
        '202':
          description: Server accepted and queued the request for background execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
            text/json:
              schema:
                $ref: '#/components/schemas/BackgroundApiAcceptedDto'
      security:
      - interactiveapi: []
      x-summary-source: derived
components:
  schemas:
    MetadataDto:
      type: object
      properties:
        totalCount:
          type: integer
          format: int64
        maxPageSize:
          type: integer
          format: int64
    vatPayableSubaccountInVatGlAccountsDto:
      properties:
        active:
          type: boolean
        id:
          type: string
          description: Click on the magnifier. &gt; The identifier.
        description:
          type: string
          description: Click on the magnifier. &gt; The description.
      description: 'Mandatory field: VAT payable subaccount* &gt; The corresponding VAT payable subaccount.'
    vatClaimableSubccountInVatGlAccountsDto:
      properties:
        active:
          type: boolean
        id:
          type: string
          description: Click on the magnifier. &gt; The identifier.
        description:
          type: string
          description: Click on the magnifier. &gt; The description.
      description: VAT claimable subaccount &gt; The corresponding tax claimable subaccount.
    VatCategoryDto:
      type: object
      properties:
        vatCategoryId:
          type: string
          description: 'Mandatory field: The top part &gt; VAT category ID* &gt; The unique ID of the VAT category. An alphanumeric string of up to six characters can be used.'
        description:
          type: string
          description: The top part &gt; Description &gt; A detailed description of the category.
        active:
          type: boolean
          description: The top part &gt; Active &gt; A check box that means (if selected) that this VAT category is active.
        excludeListedTaxes:
          type: boolean
          description: The top part &gt; Exclude listed taxes &gt; A check box that indicates (if selected) this VAT category should exclude the listed taxes from VAT zones.
        lastModifiedDateTime:
          type: string
          description: Systemgenerated information.
          format: date-time
        vatCategoryLines:
          type: array
          items:
            $ref: '#/components/schemas/VatCategoryLineDto'
          description: The table &gt;
    defaultNonStockItemInVatInformationDto:
      properties:
        number:
          type: string
          description: Number of item
        description:
          type: string
          description: Name of item/description
      description: VAT settings tab &gt; Default non-stock item &gt; The default non-stock item for the VAT ID.
    UpdateNoteDto:
      type: object
      properties:
        note:
          $ref: '#/components/schemas/noteInUpdateNoteDto'
    noteInUpdateNoteDto:
      properties:
        value:
          type: string
      description: Note for Vat report header.
    BackgroundApiAcceptedDto:
      type: object
      properties:
        id:
          type: string
        stateLocation:
          type: string
    glAccountsInVatInformationDto:
      properties:
        vatPayableAccount:
          $ref: '#/components/schemas/vatPayableAccountInVatGlAccountsDto'
        vatPayableSubaccount:
          $ref: '#/components/schemas/vatPayableSubaccountInVatGlAccountsDto'
        vatClaimableAccount:
          $ref: '#/components/schemas/vatClaimableAccountInVatGlAccountsDto'
        vatClaimableSubccount:
          $ref: '#/components/schemas/vatClaimableSubccountInVatGlAccountsDto'
      description: General ledger accounts &gt;
    TaxCategoryNumberDescriptionDto:
      type: object
      properties:
        number:
          type: string
          description: Number of item
        description:
          type: string
          description: Name of item/description
    VatInformationScheduleDto:
      type: object
      properties:
        startDate:
          type: string
          description: 'Mandatory field: Start date &gt; The date when the VAT at the rate in the current row becomes effective.'
          format: date-time
        vatRate:
          type: number
          description: VAT rate &gt; The VAT rate (%) that is used to calculate the VAT amount.
          format: double
        minTaxableAmt:
          type: number
          description: Min. taxable amount &gt; The minimum taxable amount for which this rate is applicable.
          format: double
        maxTaxableAmt:
          type: number
          description: Max. taxable amount &gt; The maximum taxable amount for which this rate applies.
          format: double
        reportingGroup:
          type: string
          description: Reporting group &gt; The reporting group for the VAT.
        deductibleVatRate:
          type: number
          description: Deductible VAT rate &gt; The VAT rate (%) that is used to calculate the amount deductible from the output VAT.
          format: double
        groupType:
          enum:
          - Output
          - Input
          type: string
          description: Group type &gt; The type of the reporting group.
    VatRateLineDto:
      type: object
      properties:
        revisionID:
          type: string
          description: The revision ID of the VAT rate.
        vatRate:
          type: number
          description: The VAT rate of the line.
          format: double
        groupType:
          enum:
          - Output
          - Input
          type: string
          description: The type of the reporting group.
        startDate:
          type: string
          description: The date and time from which the VAT rate is effective.
          format: date-time
    vatAgencyIdInVatInformationDto:
      properties:
        internalId:
          type: integer
          description: The internal id of the supplier
          format: int64
        number:
          type: string
          description: Click the magnifier. &gt; The identifier.
        name:
          type: string
          description: Click the magnifier. &gt; The name.
      description: VAT settings tab &gt; Tax agency &gt; The name of the tax agency to receive the VAT.
    VatZoneDto:
      type: object
      properties:
        id:
          type: string
          description: Click the magnifier. The identifier for the VAT zone of the supplier, which is specified in the  AP303000 window.
        description:
          type: string
          description: Click the magnifier. The description for the VAT zone of the supplier, which is specified in the  AP303000 window.
        defaultVatCategory:
          type: string
          description: Click the magnifier. The Default VAT category for the VAT zone of the supplier, which is specified in the  AP303000 window.
        defaultTaxCategory:
          $ref: '#/components/schemas/TaxCategoryNumberDescriptionDto'
        errorInfo:
          type: string
        metadata:
          $ref: '#/components/schemas/MetadataDto'
    vatPayableAccountInVatGlAccountsDto:
      properties:
        type:
          enum:
          - Asset
          - Liability
          - Income
          - Expense
          type: string
          description: Account &gt; The account number.
        externalCode1:
          type: string
          description: Account class &gt; The identifier of the account class.
        externalCode2:
          type: string
          description: Account class &gt; The name of the account class.
        active:
          type: boolean
        number:
          type: string
          description: Number of item
        description:
          type: string
          description: Name of item/description
      description: 'Mandatory field: VAT payable account* &gt; The liability account that accumulates the VAT amounts to be paid to a tax agency for the VAT reporting period.'
    VatCategoryLineDto:
      type: object
      properties:
        vatId:
          type: string
          description: 'Mandatory field: VAT ID* &gt; The ID of the VAT included in the category.'
        vendorCd:
          type: string
          description: Vendor code &gt; The vendor number associated with the VAT category line.
        description:
          type: string
          description: Description &gt; The detailed description of the VAT item.
        type:
          enum:
          - Sales
          - Use
          - Vat
          - Withholding
          - ExemptVat
          - StatisticalVat
          - DirectVat
          - PendingVat
          - ReverseVat
          type: string
          description: VAT type &gt; The type of VAT, which defines how it is processed.
        calculateOn:
          enum:
          - ExtractFromItemAmount
          - ItemAmount
          - ItemTaxAmount
          - DocumentAmount
          - DocumenTaxAmount
          type: string
          description: 'Calculate on &gt; The way the VAT amount is calculated, which can be one of the following options: Extract from item amount, Document amount, Document and VAT amount.'
        cashDiscount:
          enum:
          - ToTaxableAmount
          - ToPromtPayment
          - ToTaxAmount
          - AdjustTax
          - NoAdjust
          type: string
          description: 'Cash discount &gt; The method of calculating the taxable amount if a discount is applied (based on the credit terms). It can be one of the following options: Reduce VAT amount, Does not affect VAT amount.'
        vatRates:
          type: array
          items:
            $ref: '#/components/schemas/VatRateLineDto'
    vatClaimableAccountInVatGlAccountsDto:
      properties:
        type:
          enum:
          - Asset
          - Liability
          - Income
          - Expense
          type: string
          description: Account &gt; The account number.
        externalCode1:
          type: string
          description: Account class &gt; The identifier of the account class.
        externalCode2:
          type: string
          description: Account class &gt; The name of the account class.
        active:
          type: boolean
        number:
          type: string
          description: Number of item
        description:
          type: string
          description: Name of item/description
      description: VAT Claimable account &gt; The account that accumulates the VAT amounts to be claimed from the tax agency for the VAT reporting period.
    VatInformationDto:
      type: object
      properties:
        vatCategoryId:
          type: string
          description: VatCategoryId is deprecated, please use Vat Id instead
        vatId:
          type: string
          description: 'Mandatory field: VAT settings tab &gt; VAT ID* &gt; The unique ID of the VAT.'
        description:
          type: string
          description: VAT settings tab &gt; Description &gt; A detailed description of the VAT.
        type:
          enum:
          - Sales
          - Use
          - Vat
          - Withholding
          - ExemptVat
          - StatisticalVat
          - DirectVat
          - PendingVat
          - ReverseVat
          type: string
          description: VAT settings tab &gt; VAT type &gt; The type of VAT.
        deductibleVat:
          type: boolean
          description: VAT settings tab &gt; Partially deductible VAT &gt; A check box that indicates (if selected) that this is a deductible value-added VAT.
        reverseVat:
          type: boolean
          description: VAT settings tab &gt; Reverse VAT &gt; A check box that indicates (if selected) that this is a reverse VAT.
        statisticalVat:
          type: boolean
          description: VAT settings tab &gt; Statistical VAT &gt; A check box that indicates (if selected) that the VAT on documents will be calculated only for statistical purposes or will be reported only but not actually paid.
        pendingVat:
          type: boolean
          description: VAT settings tab &gt; Pendig VAT &gt; A check box that indicates (if selected) that the VAT that should be calculated in documents, but should not be recorded to the VAT report until the VAT invoice is received.
        includeinVatExemptTotal:
          type: boolean
          description: VAT settings tab &gt; Include in VAT exempt total &gt; A check box that indicates (if selected) that this value-added VAT has a zero rate and is used to calculate a document subtotal that is actually exempt from VAT.
        includeinVatTotal:
          type: boolean
          description: VAT settings tab &gt; Include in VAT taxable total &gt; A check box that indicates (if selected) that the VAT taxable amount should appear in the VAT taxable total field in the documents (such as invoices).
        enterFromVatInvoice:
          type: boolean
          description: VAT settings tab &gt; Enter from VAT invoice &gt; A check box that indicates (if selected) that this VAT should be calculated for documents only if the documents are added to a VAT invoice or VAT adjustment.
        calculateOn:
          enum:
          - ExtractFromItemAmount
          - ItemAmount
          - ItemTaxAmount
          - DocumentAmount
          - DocumenTaxAmount
          type: string
          description: 'VAT settings tab &gt; Calculate on &gt; The method of calculating the tax amount, which is one of the following options: Extract from item amount, Item amount, Item and VAT amount, Document amount, Document and VAT amount.'
        cashDiscount:
          enum:
          - ToTaxableAmount
          - ToPromtPayment
          - ToTaxAmount
          - AdjustTax
          - NoAdjust
          type: string
          description: VAT settings tab &gt; Cash discount &gt; The method of calculating the tax base amount if a cash discount is applied.
        vatAgencyId:
          $ref: '#/components/schemas/vatAgencyIdInVatInformationDto'
        notValidAfter:
          type: string
          description: VAT settings tab &gt; Not valid after &gt; The date after which the VAT is not effective.
          format: date-time
        euReportCode:
          enum:
          - SalesOfGoods
          - Triangulation
          - SalesOfService
          type: string
          description: VAT settings tab &gt; EU report code &gt; The EU reporting code for the VAT.
        documentText:
          type: string
          description: VAT Settings tab &gt; Document text tab &gt; Document text &gt; The text to be printed to the VAT document.
        defaultNonStockItem:
          $ref: '#/components/schemas/defaultNonStockItemInVatInformationDto'
        vismaXmlVatType:
          enum:
          - VatTypeHigh
          - VatTypeMedium
          - VatTypeLow
          - VatTypeZero
          - VatTypeExempt
          type: string
          description: VAT settings tab &gt; Visma XML VAT type &gt; The VAT type to be used in Visma XML files.
        lastModifiedDateTime:
          type: string
          description: System generated information.
          format: date-time
        glAccounts:
          $ref: '#/components/schemas/glAccountsInVatInformationDto'
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/VatInformationScheduleDto'
          description: Both tabs &gt; VAT schedule &gt;
        categories:
          type: array
          items:
            $ref: '#/components/schemas/VatCategoryDto'
          description: Both tabs &gt; Categories tab &gt;
        zones:
          type: array
          items:
            $ref: '#/components/schemas/VatZoneDto'
          description: Both tabs &gt; Zones tab &gt;
  securitySchemes:
    interactiveapi:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://connect.visma.com/connect/authorize
          tokenUrl: https://connect.visma.com/connect/token
          scopes:
            vismanet_erp_interactive_api:read: vismanet_erp_interactive_api:read
            vismanet_erp_interactive_api:update: vismanet_erp_interactive_api:update
            vismanet_erp_interactive_api:create: vismanet_erp_interactive_api:create
            vismanet_erp_interactive_api:delete: vismanet_erp_interactive_api:delete
            vismanet_erp_interactive_api:ui-extension: vismanet_erp_interactive_api:ui-extension