openapi: 3.0.3
info:
  title: Pagero Online Tax Reporting API
  description: "This documentation describes the Tax Reporting API. The Tax Reporting API is responsible for all operations related to \nsending files to Pagero Online specifically for reporting processes in CTC markets. \nThis includes sending data to the accounts configured Reporting Authority, managing possible errors and making reporting process statuses available for consumption.\n\nThe Tax Reporting API aims to report transactional and accounting data to compulsory platforms in different jurisdictions through two distinct approaches:\n\n* Transactional data only, single payload, processed and reported in real time.\n* Aggregated data reported periodically.\n\nThese reporting scenarios encompass various tax data report types, including Invoice Report, Payment, and Receipt Transaction.\nPayment includes support for both Invoice and Receipt Transactions payment confirmation.\n\n# Resources\n\n## Tax Data Report\n\nA tax data report represents the file containing one individual tax filing that represent specific financial data for a designated transaction or period.\nIt contains detailed individual transactions or aggregated data points. Attributes of a tax data report include its Id,\nsent time, account type (Accounts Payable or Accounts Receivable), status (Approved, Rejected, Technical Error, Processing, Processed or Delivered), \nstatus description, tax data report type (Invoice, Receipt Transaction, Payment Status), net amount, total amount,\ntotal VAT amount, seller and buyer names, and their respective countries.\n\n## Notification\n\nA Tax Data Report Notification represents the response from the reporting authority after processing a tax data report. \nOnce a tax data report is submitted for reporting, the authority returns a response, which is forwarded to the customer as a notification. \nThis notification includes the received response status from the reporting authority, reporting details, and referenced document information, \nensuring transparency in the reporting process. The notification feature is account-based and requires configuration to be enabled.\n\n\n# Concepts\n\n## Reporting Authority\n\nThe \"Reporting Authority\" refers to the specific national tax infrastructure associated with the selected market. Which Reporting Authority the account in question is connected towards for reporting purposes is determined based on account level settings.   \n\n## Tax Reporting Statuses\n\n### Tax data reports\n\n* Approved - Tax data report is approved by the receiving authority\n\n* Processing - Tax data report is being processed by the service\n\n* Processed - Tax data report sent in Certified mode will be marked as “Processed” as the final status since no delivery to the authority occurred  \n\n* Delivered - Tax data report is successfully delivered to the authority  \n\n* Rejected - Tax data report is rejected by the receiving authority\n\n* Technical Error - Tax data report contains errors identified during processing through Pagero Online.\n\n\n## Tax Data Report Types\n\nThere are three categories that provided tax data reports will be separated between:\n\n- *Invoice Report* - Tax data report containing data which correspond to a Sales or Purchase Invoice\n\n- *Receipt Transaction* - Tax data report containing data which related to transactions which did not give raise to an invoice. For example, point-of-sales transactions. \n\n- *Payment Report* - Tax data report containing data which confirms payment has been received. It can be used to confirm payment of either an Invoice or a Receipt Transaction    \n\n## Account Types\n\nThere are two types of accounts: \n- *Account Payable* - Tax data reports corresponding to expense reporting.\n\n- *Account Receivable* - Tax data reports corresponding to income reporting\n"
  contact:
    email: support@pagero.com
  version: 1.3.0
servers:
- url: https://virtserver.swaggerhub.com/pagero-api/tax-data-reporting-api/1.3.0
  description: SwaggerHub API Auto Mocking
- url: https://api.pageroonline.com/taxdatareporting/v1/
tags:
- name: tax data report
  description: Operations on tax data reports
- name: notification
  description: Operations on notifications
paths:
  /taxdatareports:
    get:
      tags:
      - tax data report
      summary: Get tax data reports
      description: |
        Get `Tax data report`
      parameters:
      - name: companyId
        in: query
        description: "Id of the company to get tax data reports for. If not provided, tax data reports for all companies the user has access to are returned."
        required: false
        schema:
          type: string
      - name: createTimeFrom
        in: query
        description: Exclude tax data reports created before this date and time. Date and time should be expressed in ISO 8601 format with timezone.
        required: false
        schema:
          type: string
          example: 2025-03-25T04:38:10Z
      - name: createTimeTo
        in: query
        description: Exclude tax data reports created after this date and time. Date and time should be expressed in ISO 8601 format with timezone.
        required: false
        schema:
          type: string
          example: 2025-03-25T04:38:10Z
      - name: modifiedTimeFrom
        in: query
        description: Exclude tax data reports modified before this date and time. Date and time should be expressed in ISO 8601 format with timezone.
        required: false
        schema:
          type: string
          example: 2025-03-25T04:38:10Z
      - name: modifiedTimeTo
        in: query
        description: Exclude tax data reports modified before this date and time. Date and time should be expressed in ISO 8601 format with timezone.
        required: false
        schema:
          type: string
          example: 2025-03-25T04:38:10Z
      - name: taxDataReportTypes
        in: query
        description: Comma-separated tax data report types of the tax data reports to filter on.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Receipt Transaction
            - Payment
            - Invoice
      - name: searchTerm
        in: query
        description: The search term can match either the identifier or the sender reference. A wildcard character is automatically added at the beginning and end of the search term. The search will automatically be performed in a case-insensitive manner.
        required: false
        schema:
          type: string
      - name: accountTypes
        in: query
        description: Comma-separated account types of the tax data reports to filter on.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Payable
            - Receivable
      - name: sendModes
        in: query
        description: "Comma-separated send modes of the tax data reports to filter on. If not provided, tax data reports for all send modes are returned."
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Production
            - Certification
            - Test
      - name: statuses
        in: query
        description: Comma-separated statuses of the tax data reports to filter on.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Approved
            - Rejected
            - Processing
            - Processed
            - Delivered
            - Technical Error
      - name: sort
        in: query
        description: The property to sort on. The default direction is ascending. Prepend property with '-' to sort in descending order. Sortable properties are createTime and modifiedTime. Default sorting order is createTime descending.
        required: false
        schema:
          type: string
        examples:
          asc:
            summary: Sort by modified time in ascending order
            value: modifiedTime
          desc:
            summary: Sort by modified time in descending order
            value: -modifiedTime
      - name: offset
        in: query
        description: The number of items to skip before starting to collect the result set.
        required: false
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: The maximum number of items in the collection resource response.
        required: false
        schema:
          maximum: 1000
          minimum: 0
          type: integer
          format: int32
          default: 10
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaxDataReports"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
      - tax data report
      summary: Post a tax data report
      description: Send a tax data report to Pagero Online. The request should be a multipart request containing the actual tax data report data and the rest of the properties. The `Content-Type` of the request should be `multipart/form-data`.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/TaxDataReportRequest"
            example:
              payload: (binary file content)
              sendingCompanyId: ABC123
              sendMode: Test
              senderReference: invoice-test.xml
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaxDataReportResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "406":
          $ref: "#/components/responses/NotAcceptable"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /taxdatareports/{id}:
    get:
      tags:
      - tax data report
      summary: Get a tax data report by id
      description: Get a `tax data report from a specific id`.
      parameters:
      - name: id
        in: path
        description: |
          Tax data report id to get a tax data report for.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaxDataReport"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "404":
          $ref: "#/components/responses/NotFound"
  /taxdatareports/{id}/target:
    get:
      tags:
      - tax data report
      summary: Get a tax data report target
      description: Get target document for a `Tax Data Report`.
      parameters:
      - name: id
        in: path
        description: Id of the `Tax Data Report`.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /taxdatareports/action:
    post:
      tags:
      - tax data report
      summary: Perform an action on multiple tax data reports
      description: Perform an action on multiple `tax data reports` that are either in Rejected status or Technical Error status.
      requestBody:
        content:
          application/json:
            schema:
              required:
              - action
              - ids
              - userComment
              type: object
              properties:
                ids:
                  type: array
                  description: "A comma separated list tax data report ids, to performed the specified action on."
                  items:
                    type: integer
                    format: int32
                action:
                  type: string
                  description: |
                    The action to perform on the tax data reports that are either in Rejected status or Technical Error status.
                    Possible values:
                    - "Restart"
                    - "Cancel"
                userComment:
                  type: string
                  description: User comment to be added when performing the action.
              example:
                ids:
                - 2353
                - 2354
                - 3523
                - 3524
                action: Restart
                userComment: Test restart
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaxDataReportActionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "404":
          $ref: "#/components/responses/NotFound"
  /notifications:
    get:
      tags:
      - notification
      summary: Get notifications
      description: |
        Get `Notifications`.
      parameters:
      - name: companyId
        in: query
        description: "Id of the company to get notifications for. If not provided, notifications for all companies the user has access to are returned"
        required: false
        schema:
          type: string
      - name: createTimeFrom
        in: query
        description: Exclude notification created before this date and time. Date and time should be expressed in ISO 8601 format with timezone.
        required: false
        schema:
          type: string
          example: 2025-03-25T04:38:10Z
      - name: createTimeTo
        in: query
        description: Exclude notification created after this date and time. Date and time should be expressed in ISO 8601 format with timezone.
        required: false
        schema:
          type: string
          example: 2025-03-25T04:38:10Z
      - name: taxDataReportId
        in: query
        description: "Id of the tax data report. The tax data report id is returned when posting a report in the API. If provided, notifications for tax data report id are returned"
        required: false
        schema:
          type: integer
          format: int32
      - name: searchTerm
        in: query
        description: The search term can match either the notification receiver name or the notification sender name. A wildcard character is automatically added at the beginning and end of the search term. The search will automatically be performed in a case-insensitive manner.
        required: false
        schema:
          type: string
      - name: sendModes
        in: query
        description: "Comma-separated send modes of the notification to filter on. If not provided, notifications for all send modes are returned"
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Production
            - Certification
            - Test
      - name: sort
        in: query
        description: The property to sort on. Prepend property with '-' to sort in descending order. Sortable property is createTime. Default sorting order is createTime descending.
        required: false
        schema:
          type: string
        examples:
          asc:
            summary: Sort by create time in ascending order
            value: createTime
          desc:
            summary: Sort by create time in descending order
            value: -createTime
      - name: offset
        in: query
        description: The number of items to skip before starting to collect the result set.
        required: false
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: The maximum number of items in the collection resource response.
        required: false
        schema:
          maximum: 1000
          minimum: 0
          type: integer
          format: int32
          default: 10
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notifications"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /notifications/{id}/target:
    get:
      tags:
      - notification
      summary: Get a notification target
      description: Get target document for a `Notification`.
      parameters:
      - name: id
        in: path
        description: Id of the `Notification`.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  schemas:
    CollectionMetadata:
      required:
      - limit
      - offset
      - total
      type: object
      properties:
        offset:
          type: integer
          description: The number of items to skip before starting to collect the result set.
          format: int32
          example: 0
        limit:
          type: integer
          description: The maximum number of items in the collection resource response. Please note that there is always an upper bound to this property which may vary between different APIs and resources.
          format: int32
          example: 10
        total:
          type: integer
          description: The total number of items in the collection.
          format: int32
          example: 55
    TaxDataReports:
      required:
      - items
      - meta
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/CollectionMetadata"
        items:
          type: array
          items:
            $ref: "#/components/schemas/TaxDataReport"
    TaxDataReport:
      type: object
      properties:
        id:
          type: integer
          description: Id of the tax data report.
          format: int32
          example: 12345
        authorityReportName:
          type: string
          description: name of the tax data report.
          example: Test123
        identifier:
          type: string
          description: Identifier of the tax data report.
          example: ABC123
        taxDataReportType:
          $ref: "#/components/schemas/TaxDataReportTypeEnum"
        accountType:
          $ref: "#/components/schemas/AccountTypeEnum"
        sendMode:
          $ref: "#/components/schemas/SendModeEnum"
        clearanceId:
          type: string
          description: The unique identifier given by the reporting authority for the tax data report.
          example: 550e8400-e29b-41d4-a716-446655440000
        senderName:
          type: string
          description: Name of the sender.
          example: Test Company
        receiverName:
          type: string
          description: Name of the receiver.
          example: Test Authority
        status:
          type: string
          description: |
            The status of the tax data report. Possible values:
            - "Processing"
            - "Processed"
            - "Delivered"
            - "Rejected"
            - "Approved"
            - "Technical Error"
          example: Approved
        statusText:
          type: string
          description: Description of the status.
          example: Report was approved by Test Authority
        createTime:
          type: string
          description: "Create time of the tax data report, expressed in ISO 8601 format with timezone."
          example: 2025-03-25T04:38:10Z
        modifiedTime:
          type: string
          description: "Modified time of the tax data report, expressed in ISO 8601 format with timezone."
          example: 2025-03-25T05:12:20Z
        deliveredTime:
          type: string
          description: "Delivery time of the tax data report to the receiving authority, expressed in ISO 8601 format with timezone."
          example: 2025-03-25T04:41:15Z
        companyId:
          type: string
          description: Id of the company.
        originatingFileId:
          type: string
          description: Id of the originating file.
          example: I-123456789
        originatingDocumentId:
          type: string
          description: Id of the originating document.
          example: 01a23456-7b89-1a2b-c1de-42ee4b8cabb5
      description: The tax data report details
    Actions:
      type: object
      properties:
        Restart:
          type: string
        Cancel:
          type: string
      description: List of actions available.
    Notifications:
      required:
      - items
      - meta
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/CollectionMetadata"
        items:
          type: array
          items:
            $ref: "#/components/schemas/Notification"
    Notification:
      type: object
      properties:
        id:
          type: integer
          description: Id of the notification.
          format: int32
          example: 123
        taxDataReportId:
          type: integer
          description: Id of the tax data report.
          format: int32
          example: 12345
        companyId:
          type: string
          description: Id of the company that received the notification.
          example: ABC123
        createTime:
          type: string
          description: "Create time of the notification, expressed in ISO 8601 format with timezone."
          example: 2025-03-25T04:38:11Z
        status:
          type: string
          description: |
            The status of the notification. Possible values:
            - "Delivered"
          example: Delivered
        statusText:
          type: string
          description: Description of the status.
          example: Notification Delivered Successfully
        sendMode:
          $ref: "#/components/schemas/SendModeEnum"
        filename:
          type: string
          description: Filename of the notification document.
          example: notification123.xml
        senderName:
          type: string
          description: sender name (authority) of the notification.
          example: Test Authority
        receiverName:
          type: string
          description: receiver name (company) of the notification.
          example: Test Company
        originatingFileId:
          type: string
          description: Id of the originating file.
          example: I-123456789
        originatingDocumentId:
          type: string
          description: Id of the originating document.
          example: 01a23456-7b89-1a2b-c1de-42ee4b8cabb5
      description: The notification details
    TaxDataReportRequest:
      required:
      - payload
      - sendMode
      type: object
      properties:
        payload:
          type: string
          description: The tax data report to send.
          format: binary
        sendingCompanyId:
          type: string
          description: "If the sending user has access to more than one company, this field must be provided to specify which company the file is being sent for. If a user has access to only one company, it is assumed that the file is sent for that company and this property can be left out."
        sendMode:
          $ref: "#/components/schemas/SendModeEnum"
        senderReference:
          type: string
          description: "The sender's reference to the tax data report, for example a file name."
    TaxDataReportResponse:
      type: object
      properties:
        id:
          type: integer
          description: A unique id of the tax data report.
          format: int32
          example: 12345
        senderReference:
          type: string
          description: Reference added by sender.
          example: invoice123.xml
        createTime:
          type: string
          description: "Created time of the tax data report, expressed in ISO 8601 format with timezone."
          example: 2025-03-25T04:38:11Z
        sendingCompany:
          type: object
          properties:
            id:
              type: string
              description: Identifier of the sending company.
              example: ABC123
          description: The company that sent the tax data report.
        sendMode:
          $ref: "#/components/schemas/SendModeEnum"
    TaxDataReportActionResponse:
      type: object
      properties:
        ids:
          type: array
          description: List of tax data reports ids that successfully validated for the requested action
          example:
          - 2353
          - 2354
          items:
            type: integer
            format: int32
        actionFailureDetails:
          type: array
          description: "List of tax data report ids that failed for the requested action, including the report id and reason for failure"
          example:
          - id: 3523
            errorMessage: "Tax data report [id=3523] has invalid status for restart. Status: DELIVERED"
          - id: 3524
            errorMessage: "Tax data report [id=3524] has invalid status for restart. Status: DELIVERED"
          items:
            type: object
            properties:
              id:
                type: integer
                description: Id of the tax data report that failed for the requested action
                format: int32
                example: 3523
              errorMessage:
                type: string
                description: Reason why the tax data report action failed for the requested action
                example: "Tax data report [id=3523] has invalid status for restart. Status: DELIVERED"
      description: List of successfully validated tax data report ids and details of failures for the requested action
    AccountTypeEnum:
      title: AccountTypeEnum
      type: string
      description: |
        Account type. Possible values:
        - "Payable"
        - "Receivable"
      example: Payable
    TaxDataReportTypeEnum:
      title: TaxDataReportTypeEnum
      type: string
      description: "Tax Data Report type. Possible values: \n- \"Receipt Transaction\"\n- \"Payment\"\n- \"Invoice\"\n"
      example: Invoice
    SendModeEnum:
      title: SendModeEnum
      type: string
      description: |
        Send mode.

        * **Production** - Production mode

        * **Test** - Test mode. Documents will be delivered to the recipients but will be delivered in test mode if the recipients support it. Please note that not all recipients support test mode.

        * **Certification** - Certification mode. Documents will be processed by Pagero Online but will not be delivered to the recipients. This can be useful during testing.
      example: Test
      enum:
      - Production
      - Test
      - Certification
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: Request is missing required HTTP header 'Accept'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: The call is unauthorized
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: User must have required permissions!
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: No data found for given id
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: Internal Server Error occurred while fetching data
    UnsupportedMediaType:
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: "Content-Type is not supported. Expected: multipart/form-data"
    NotAcceptable:
      description: Not Acceptable.
      content:
        application/json:
          schema:
            type: string
            description: Error message
          example: "Resource representation is only available with these types: application/json"
  parameters:
    offset:
      name: offset
      in: query
      description: The number of items to skip before starting to collect the result set.
      required: false
      schema:
        minimum: 0
        type: integer
        format: int32
        default: 0
    limit:
      name: limit
      in: query
      description: The maximum number of items in the collection resource response.
      required: false
      schema:
        maximum: 1000
        minimum: 0
        type: integer
        format: int32
        default: 10
