openapi: 3.0.3
info:
  title: Pagero Online File API
  description: "# Introduction\nThis documentation describes the File API functionality. The File API is responsible for everything related to sending files to Pagero Online. This includes sending files and managing possible errors or other required client actions.\n# Key Concepts\nThis section describes the key concepts of the File API.\n## File\nA `File` represents the actual file that was originally sent from the client and the metadata sent with it.\n## Filepart\nA `File` is processed in Pagero Online in several steps. The original `File` is split into smaller parts that are processed individually. As an example, the original file sent to Pagero Online may be a zip file which gets split into one or more pdf files. Each pdf file may then get split into one or more documents. The concept of a `Filepart` is used to describe anything that gets processed in Pagero Online, regardless of the current form (ZIP, PDF, XML or or anything else).\n\nA `Filepart` will always be in any one of the following states:\n* **Processing** - The `Filepart` is currently being processed by Pagero Online. This normally takes a couple of seconds, unless the `Filepart` needs to be manually handled by Pagero Support.  \n* **Awaiting interaction** - The `Filepart` is waiting for interaction from the client.\n* **Error** - The `Filepart` has encountered an error that needs to be handled by the client.\n* **Cancelled** - The `Filepart` has been cancelled, which means it will not be processed or delivered.\n\nA `Filepart` which has been successfully processed will not be visible in the API.\n## Document\nA `Document` is a generic term for a business document, such as an invoice, an order or an order response. Whenever a `File` has been processed successfully, the result will be one or more `Documents`. `Documents` can be accessed through the Document API.\n# Workflow\nThis section describes a typical workflow when sending files through the File API.\n## Send a File to Pagero Online\nA file is sent to Pagero Online by making a `POST` request to the `/files` endpoint. The created `File` resource will be returned in the response. The sent file must be in a format that Pagero Online recognises.\n## Get Information About a Sent File\nUse the `/files` or `/files/{id}` endpoints to get information about a sent file. Please note however that these endpoints will not give any information about the processing of the `File`. For this purpose, use the `/fileparts` endpoint.\n## Check for Errors and Required Actions\nWhen `Fileparts` are processed, they may end up in a state which requires interaction from the client. To get hold of all Fileparts that require an action, make a `GET` request to the `/fileparts` endpoint with the query parameter `status=AwaitingInteraction,Error`. This will return all Fileparts that the client currently needs to handle.\n### Check periodically\nSome of the operators which Pagero Online delivers documents to only respond when there is a delivery failure. Since no response is received on a successful delivery, Pagero Online assumes that anything delivered to these operators has been successfully delivered until a response is received which says otherwise. This means that a client needs to periodically check for `Fileparts` to handle, since a `Filepart` which was previously believed to be delivered successfully may change status so that it requires an action from the client.\n## Adding Attachments\nA company can be configured in Pagero Online to have 'manual attachment handling'. This means that all documents that are sent to Pagero Online will stop in the middle of processing and wait for attachments to be added.    \n### Get Fileparts awaiting Attachments\nTo get hold of all `Fileparts` that are awaiting attachments, make a `GET` request to the `/fileparts` endpoint and provide `status=AwaitingInteraction` as parameter. From the result, filter out all `Fileparts` where the `awaitingInteractionOperations` property equals `AddAttachments`.  \n### Add Attachment to Filepart\nTo add an attachment to a `Filepart`, make a `POST` request to the `/fileparts/{id}/attachments` endpoint.\n### Resume processing of a Filepart\nWhen all attachments have been added, the processing of the `Filepart` must be resumed. This is done by posting a `Resume` action to the `/fileparts/{id}/actions` endpoint.\n## Handle errors\nWhen a `Filepart` is in error status (`status=Error`), it will contain an `error` object which describes the error. The `possibleActions` property describes the actions that can be taken on the `Filepart`. To post an action, make a `POST` request to the `/fileparts/{id}/actions` endpoint.\n\n* **`Restart`** - If the error can be solved manually in Pagero Online, the client can do this and then post a `Restart` action on the erroneous `Filepart`. For instance, if a recipient can not be reached because it has not yet been connected in Pagero Online, the problem can be fixed in Pagero Online (or through the API) after which the `Filepart` can be restarted.\n\n* **`Cancel`** - If there is nothing you can do about an erroneous `Filepart`, the `Cancel` action can be posted on it. This means the `Filepart` will be ignored. Sometimes this may be the only action available.  \n\n### Handling resolvable document errors\nThere is a specific category of errors called 'Document errors'. This means that there's something wrong with the actual document data, and that the problem can be fixed by replacing that invalid data.\nIf the `error` object contains a list of document errors, these errors can be resolved by posting a `RestartWithReplacements` action on the `/fileparts/{id}/actions` endpoint, along with a list of `Replacements` that specify new values for the invalid document data. \n\nExample:\n\n`GET` `/fileparts/{id}`\n\n    ...  \n    \"error\": {\n              \"description\": \"Description of the error\",\n              \"documentErrors\": [\n                  {\n                      \"title\": \"The title of the resolvable error\",\n                      \"description\": \"The description of the resolvable error\",\n                      \"errorValue\": \"The incorrect value in the document\",\n                      \"errorReference\": \"The error reference\"\n                  }\n              ]\n          },\n    \"possibleActions\": [\n              \"RestartWithReplacements\",\n              ...\n          ],\n    ...      \n\nResolve the error by posting an action to `/fileparts/{id}/action` \n\n       ...\n      {\n         \"action\": \"RestartWithReplacements\",\n         \"replacements\": [\n           {\n             \"errorReference\": \"The errorReference from the response above\",\n             \"newValue\": \"The value that should replace errorValue\"\n           }\n         ],\n         \"reason\": \"The reason for the restart\"\n      },\n      ...\n\n# Changelog\n## 1.1.0\n* Added `modifiedTime` in response for `GET /fileparts` endpoint.\n* Added query parameters `modifiedTimeFrom`, `modifiedTimeTo`, `createTimeFrom` and `createTimeTo` in `GET /fileparts` endpoint.\n\n## 2.0.0\n* A `Filepart` can now also have the status `Cancelled`. Cancelled fileparts are included by default in the `GET /fileparts` endpoint. It is also possible to filter on the `Cancelled` status, just like any other status.\n\n## 2.1.0\n* Property `documentSubtype` added to `Document`\n* Property `distribution` added to `Document`\n\n## 2.1.1\n*  In the API description, in the example for getting a filepart with a specific id, the `documentErrors` property was erroneously called `documentError`.\n## 2.2.0\n* Added `performedActions` on `Filepart`\n## 2.2.1\n* `limit` parameter for endpoint `GET /files`, `GET /files{id}/fileparts` and `GET /fileparts` was documented to have max value 1000 when it should have been 100. This has been fixed.\n## 2.2.2\n* Fixed version number in API URL (v1 => v2)\n* Fixed a spec error where `GET /attachments/{id}` returned an array of attachments instead of a single attachment.\n* Clarified specification by adding `maxLength` to strings\n* Clarified specification by adding `maxItems` to arrays\n* Added security and authentication information to the spec.\n* Added some missing descriptions to parameters and properties.\n* Added additional information to `servers`\n* Added additional information to `contact`"
  contact:
    name: Thomson Reuters / Pagero support
    url: https://www.thomsonreuters.com/en-us/help/pagero
    email: support@pagero.com
  version: 2.2.2
servers:
- url: https://api.pageroonline.com/file/v2
  description: Production server
  x-internal: false
security:
- bearerAuth: []
tags:
- name: attachment
  description: Operations on attachments
- name: file
  description: Operations on files
- name: filepart
  description: Operations on fileparts
paths:
  /attachments/{id}:
    get:
      tags:
      - attachment
      summary: Get an attachment.
      description: Get an attachment.
      parameters:
      - name: id
        in: path
        description: Id of `Attachment`
        required: true
        schema:
          maxLength: 100
          type: string
          example: bf985dab-1a43-4a08-a8c4-72dfa95ddc4c
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attachment"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
      - attachment
      summary: Delete an attachment.
      description: Delete an attachment.
      parameters:
      - name: id
        in: path
        description: Id of `Attachment`
        required: true
        schema:
          maxLength: 100
          type: string
          example: bf985dab-1a43-4a08-a8c4-72dfa95ddc4c
      responses:
        "200":
          description: Successful response
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /attachments/{id}/payload:
    get:
      tags:
      - attachment
      summary: Get payload of an attachment.
      description: Get an attachment payload.
      parameters:
      - name: id
        in: path
        description: Id of `Attachment`
        required: true
        schema:
          maxLength: 100
          type: string
          example: dba3bd06-0853-4f85-8d6d-ed1320ccd876
      responses:
        "200":
          description: Successful response
          content:
            application/octet-stream:
              schema:
                maxLength: 50000000
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /fileparts:
    get:
      tags:
      - filepart
      summary: Get fileparts.
      description: Get `Fileparts`
      parameters:
      - name: companyId
        in: query
        description: "Id of company to get `Fileparts` for. If not defined, get `Fileparts` for all companies the user has access to."
        required: false
        schema:
          maxLength: 100
          type: string
          example: e7f61b58-c4d4-4379-85f7-dea2bff619e5
      - name: fileId
        in: query
        description: Id of `File` to get `Fileparts` for.
        required: false
        schema:
          maxLength: 100
          type: string
          example: b5e039c4-7124-4472-ad95-df29db5a83d9
      - name: searchTerm
        in: query
        description: Return only `FilePart`s that match the search term. The search term will be matched against filename and document identifier.
        required: false
        schema:
          maxLength: 100
          type: string
          example: INV093845
      - name: sendMode
        in: query
        description: "The send mode used to send a document. Read more about send modes here: https://pagero.github.io/additional-functionality/send-modes"
        schema:
          $ref: "#/components/schemas/SendMode"
      - name: status
        in: query
        description: Statuses of the `Filepart`s to get.
        required: false
        style: form
        explode: false
        schema:
          maxItems: 10
          type: array
          items:
            $ref: "#/components/schemas/FilepartStatusEnum"
      - name: documentType
        in: query
        description: |
          The document type of the `Filepart`. The document type of a `Filepart` may not always be known if it was not provided for the `File` which the `Filepart` belongs to.
          Available document types are listed [here](https://pagero.github.io/partners/apis/document-types).
        required: false
        schema:
          $ref: "#/components/schemas/DocumentType"
      - name: createTimeFrom
        in: query
        description: "Only return `Fileparts` that were created after this date and time, expressed in ISO 8601 format."
        required: false
        schema:
          maxLength: 100
          type: string
          format: date-time
          example: 2024-10-29T08:57:30Z
      - name: createTimeTo
        in: query
        description: "Only return `Fileparts` that were created before this date and time, expressed in ISO 8601 format."
        required: false
        schema:
          maxLength: 100
          type: string
          format: date-time
          example: 2024-10-30T08:57:30Z
      - name: modifiedTimeFrom
        in: query
        description: "Only return `Fileparts` that were modified after this date and time, expressed in ISO 8601 format."
        required: false
        schema:
          maxLength: 100
          type: string
          format: date-time
          example: 2024-10-29T08:57:30Z
      - name: modifiedTimeTo
        in: query
        description: "Only return `Fileparts` that were modified before this date and time, expressed in ISO 8601 format."
        required: false
        schema:
          maxLength: 100
          type: string
          format: date-time
          example: 2024-10-30T08:57:30Z
      - name: expand
        in: query
        description: "A comma-separated list of response properties that should be 'expanded' into a full representation. Available properties are: sendingUser"
        required: false
        style: form
        explode: false
        schema:
          maxItems: 10
          type: array
          items:
            maxLength: 100
            type: string
            example: sendingUser
      - name: offset
        in: query
        description: The number of items to skip before returning the results
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: The number of items to return
        required: false
        schema:
          maximum: 100
          minimum: 0
          type: integer
          format: int32
          default: 10
      - name: sort
        in: query
        description: |-
          Property to sort the result set on. Available values are:
          * createTime
          * modifiedTime

          To sort in descending order, add a `'-'` before the property. Example: `-modifiedTime`.
        required: false
        schema:
          maxLength: 100
          type: string
          example: -modifiedTime
          default: -createtime
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Fileparts"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /fileparts/{id}/action:
    post:
      tags:
      - filepart
      summary: Perform an action on a filepart.
      description: Perform an action on a `Filepart`
      parameters:
      - name: id
        in: path
        description: Id of `Filepart`
        required: true
        schema:
          maxLength: 100
          type: string
          example: 08416163-86aa-421a-8c02-31af90b6b787
      requestBody:
        description: The action to perform on the `Filepart`.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FilepartAction"
        required: true
      responses:
        "200":
          description: Successful response
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /fileparts/{id}/attachments:
    get:
      tags:
      - filepart
      summary: Get attachments for a filepart.
      description: Get attachments for a filepart.
      parameters:
      - name: id
        in: path
        description: Id of `Filepart`
        required: true
        schema:
          maxLength: 100
          type: string
          example: d9add521-9abb-4a91-ad1c-dddf2ee6385c
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                maxItems: 100
                type: array
                items:
                  $ref: "#/components/schemas/Attachment"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
      - filepart
      summary: Add an attachment to a filepart.
      description: Add an attachment to a filepart. The request should be a multipart request containing the actual attachment data and the rest of the properties. The `Content-Type` of the request should be `multipart/form-data`.
      parameters:
      - name: id
        in: path
        description: Id of `Filepart`
        required: true
        schema:
          maxLength: 100
          type: string
          example: d9add521-9abb-4a91-ad1c-dddf2ee6385c
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - payload
              properties:
                attachmentType:
                  $ref: "#/components/schemas/AttachmentType"
                filename:
                  maxLength: 100
                  type: string
                  description: The original filename of the attachment
                  example: inv123_presentation.pdf
                mimetype:
                  maxLength: 100
                  type: string
                  description: The mimetype of the attachment
                  example: application/pdf
                payload:
                  maxLength: 50000000
                  type: string
                  description: The attachment file
                  format: binary
                  example: The attachment payload (binary)
        required: true
      responses:
        "201":
          description: '`Attachment` successfully created.'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attachment"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /fileparts/{id}/payload:
    get:
      tags:
      - filepart
      summary: Get the payload of a `Filepart`.
      description: Get the payload associated with this `Filepart` resource.
      parameters:
      - name: id
        in: path
        description: Id of `Filepart`
        required: true
        schema:
          maxLength: 100
          type: string
          example: 873b2eb0-63b5-45e3-a533-1cfeefa591a9
      responses:
        "200":
          description: Successful response
          content:
            application/octet-stream:
              schema:
                maxLength: 200000000
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /fileparts/{id}/presentation:
    get:
      tags:
      - filepart
      summary: Get a presentation of a `Filepart`.
      description: "Get presentation of a `Filepart`, if available."
      parameters:
      - name: id
        in: path
        description: Id of `Filepart`
        required: true
        schema:
          maxLength: 100
          type: string
          example: adf4793b-bbd8-4788-8fd3-e86c90776468
      responses:
        "200":
          description: Successful response
          content:
            application/octet-stream:
              schema:
                maxLength: 50000000
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /fileparts/action:
    post:
      tags:
      - filepart
      summary: Perform an action on multiple fileparts.
      description: Perform an action on multiple `Fileparts`.
      requestBody:
        description: The action to perform and the `Filepart` ids to perform it on.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultipleFilepartAction"
        required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                maxItems: 100
                type: array
                items:
                  $ref: "#/components/schemas/FilepartActionResult"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      x-codegen-request-body-name: action
  /files:
    get:
      tags:
      - file
      summary: Get files.
      description: Get previously sent `Files`.
      parameters:
      - name: companyId
        in: query
        description: "Id of company to get `File`s for. If not defined, get `Files` for all companies the user has access to."
        required: false
        schema:
          maxLength: 100
          type: string
          example: e0ebe47e-2d0e-4011-a564-cebb67750f08
      - name: sendMode
        in: query
        description: "The send mode used to send a document. Read more about send modes here: https://pagero.github.io/additional-functionality/send-modes"
        schema:
          $ref: "#/components/schemas/SendMode"
      - name: documentType
        in: query
        description: "The document type. Available document types are listed here: https://pagero.github.io/partners/apis/document-types"
        required: true
        schema:
          $ref: "#/components/schemas/DocumentType"
      - name: senderReference
        in: query
        description: "The sender's reference to the `File`, as provided by the sender when the `File` was created."
        required: false
        schema:
          maxLength: 1000
          type: string
          example: invoice_123
      - name: createdFrom
        in: query
        description: "Only return `Files` that were created after this date and time, expressed in ISO 8601 format."
        required: false
        schema:
          maxLength: 100
          type: string
          format: date-time
          example: 2024-09-18T13:30:30Z
      - name: createdTo
        in: query
        description: "Only return `Files` that were created before this date, expressed in ISO 8601 format."
        required: false
        schema:
          maxLength: 100
          type: string
          format: date-time
          example: 2024-09-19T13:30:30Z
      - name: expand
        in: query
        description: "A comma-separated list of response properties that should be 'expanded' into a full representation. Available properties are: sendingUser"
        required: false
        style: form
        explode: false
        schema:
          maxItems: 10
          type: array
          items:
            maxLength: 100
            type: string
            example: sendingUser
      - name: offset
        in: query
        description: The number of items to skip before returning the results
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: The number of items to return
        required: false
        schema:
          maximum: 100
          minimum: 0
          type: integer
          format: int32
          default: 10
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Files"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
      - file
      summary: Post a file.
      description: Send a file to Pagero Online. The request should be a multipart request containing the actual file data and the rest of the properties. The `Content-Type` of the request should be `multipart/form-data`.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - payload
              - sendMode
              properties:
                payload:
                  maxLength: 200000000
                  type: string
                  description: The file to send.
                  format: binary
                documentType:
                  maxLength: 100
                  type: string
                  description: "The document type of documents contained in the sent file. It is not allowed to send documents with different document types in the same file. Available document types are listed [here](https://pagero.github.io/partners/apis/document-types)."
                  example: Invoice
                sendingCompanyId:
                  maxLength: 100
                  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."
                  example: 5f1b3349-e79e-44fd-97b0-feceb78b409b
                sendMode:
                  allOf:
                  - $ref: "#/components/schemas/SendModeEnum"
                senderReference:
                  maxLength: 1000
                  type: string
                  description: "The sender's reference to the file, for example a file name."
                  example: invoice_123
        required: true
      responses:
        "201":
          description: File successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /files/{id}:
    get:
      tags:
      - file
      summary: Get a file.
      description: Get a `File`.
      parameters:
      - name: id
        in: path
        description: Id of `File`
        required: true
        schema:
          maxLength: 100
          type: string
      - name: expand
        in: query
        description: "A comma-separated list of response properties that should be 'expanded' into a full representation. Available properties are: sendingUser"
        required: false
        style: form
        explode: false
        schema:
          maxItems: 10
          type: array
          items:
            maxLength: 100
            type: string
            example: sendingUser
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /files/{id}/fileparts:
    get:
      tags:
      - file
      summary: Get fileparts for a file.
      description: Get `Filepart`s that belong to a `File`
      parameters:
      - name: id
        in: path
        description: File id
        required: true
        schema:
          maxLength: 100
          type: string
          example: 878d6119-a13a-4192-8680-5878cf674d91
      - name: expand
        in: query
        description: "A comma-separated list of response properties that should be 'expanded' into a full representation. Available properties are: sendingUser"
        required: false
        style: form
        explode: false
        schema:
          maxItems: 10
          type: array
          items:
            maxLength: 100
            type: string
            example: sendingUser
      - name: offset
        in: query
        description: The number of items to skip before returning the results
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: The number of items to return
        required: false
        schema:
          maximum: 100
          minimum: 0
          type: integer
          format: int32
          default: 10
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Fileparts"
        "400":
          $ref: "#/components/responses/BadRequestText"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /files/{id}/payload:
    get:
      tags:
      - file
      summary: Get the payload of a file.
      description: Get the payload associated with this File resource
      parameters:
      - name: id
        in: path
        description: File id
        required: true
        schema:
          maxLength: 100
          type: string
      responses:
        "200":
          description: Successful response
          content:
            application/octet-stream:
              schema:
                maxLength: 200000000
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  schemas:
    Attachment:
      type: object
      properties:
        id:
          maxLength: 100
          type: string
          description: The id of the `Attachment`
          example: 2cefd1d3-e2fb-4f61-9522-22361ab4c732
        attachmentType:
          $ref: "#/components/schemas/AttachmentType"
        filename:
          maxLength: 1000
          type: string
          description: The original filename of the attachment
          example: inv123_presentation.pdf
        mimetype:
          maxLength: 100
          type: string
          description: The mimetype of the attachment
          example: application/pdf
        payloadUrl:
          maxLength: 1000
          type: string
          description: The URL used to retrieve the attachment payload
          example: https://api.pageroonline.com/file/v2/attachments/2cefd1d3-e2fb-4f61-9522-22361ab4c732/payload
      description: An `Attachment` represents a file that is attached to a `Filepart`.
    CollectionMetadata:
      required:
      - limit
      - offset
      - total
      type: object
      properties:
        limit:
          maximum: 2147483647
          minimum: 0
          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
        offset:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: The number of items to skip before starting to collect the result set.
          format: int32
          example: 20
        total:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: The total number of items in the collection.
          format: int32
          example: 9000
      description: Metadata for a response returning a collection of resources.
    DocumentError:
      type: object
      properties:
        title:
          maxLength: 1000
          type: string
          description: Title of the document error.
          example: Invalid buyer reference
        description:
          maxLength: 1000
          type: string
          description: Description of the error.
          example: "The buyer reference is invalid. It should be A3243, B564 or C53654."
        errorValue:
          maxLength: 1000
          type: string
          description: The erroneous value previously provided in the document.
          example: A343
        errorReference:
          maxLength: 100
          type: string
          description: An error reference. Must be provided when posting an action to resolve this document error.
          example: buyerReference
      description: A `DocumentError` specifies an erroneous or missing value in a business document.
    File:
      required:
      - createTime
      - id
      - sendMode
      - sendingCompany
      - sendingUser
      type: object
      properties:
        id:
          maxLength: 100
          type: string
          example: 64f976ea-ecd3-4725-a8eb-26a34a626a71
        sendingCompany:
          description: The company that sent the `File`.
          allOf:
          - $ref: "#/components/schemas/Company"
        sendingUser:
          description: The user that sent the `File`. Only contains `id` if the 'expand' query parameter does not include 'sendingUser'.
          allOf:
          - $ref: "#/components/schemas/User"
        sendMode:
          $ref: "#/components/schemas/SendModeEnum"
        createTime:
          maxLength: 100
          type: string
          description: The date and time when the `File` was created in ISO 8601 format.
          format: date-time
          example: 2024-09-23T12:38:32Z
        documentType:
          $ref: "#/components/schemas/DocumentType"
        senderReference:
          maxLength: 1000
          type: string
          description: "The sender's reference to the file, for example a filename."
          example: inv123.xml
      description: A `File` represents a file that has been sent to Pagero Online.
    Filepart:
      required:
      - createTime
      - file
      - id
      - sendMode
      - sendingCompany
      - sendingUser
      - status
      type: object
      properties:
        id:
          maxLength: 100
          type: string
          example: 114acacc-3947-4788-b62b-85b5384969aa
        createTime:
          maxLength: 100
          type: string
          description: The creation time of the `Filepart` in ISO 8601 format.
          format: date-time
          example: 2024-09-23T12:41:53Z
        file:
          type: object
          properties:
            id:
              maxLength: 100
              type: string
              example: a0a20583-8581-4c12-a847-936e0954e723
          description: The `File` that this `Filepart` belongs to.
        sendingCompany:
          description: The sending company.
          allOf:
          - $ref: "#/components/schemas/Company"
        sendingUser:
          description: "The user that sent the `Filepart`. To get more properties than id, 'sendingUser' must be included in the 'expand' query parameter."
          allOf:
          - $ref: "#/components/schemas/User"
        sendMode:
          $ref: "#/components/schemas/SendModeEnum"
        status:
          $ref: "#/components/schemas/FilepartStatusEnum"
        processingStatus:
          type: string
          description: |
            Only available if status is `Processing`. Gives a more detailed
            description of what is happening to a `Filepart` in `Processing`
            status.

            * **Processing** - The `Filepart` is being processed by Pagero
            Online servers.

            * **HandledBySupport** - The `Filepart` has encountered a problem
            which is being manually handled by Pagero Support.

            * **AwaitingDelivery** - The `Filepart` has been successfully
            processed in Pagero Online and is waiting to be delivered. This
            includes waiting for delivery confirmation when delivering to other
            operators, which can sometimes take some time.
          example: Processing
          enum:
          - Processing
          - HandledBySupport
          - AwaitingDelivery
        awaitingInteractionOperations:
          maxItems: 100
          type: array
          description: The operations available when a `Filepart` is in status `AwaitingInteraction`.
          items:
            type: string
            example: AddAttachments
            enum:
            - AddAttachments
        possibleActions:
          maxItems: 100
          type: array
          description: Lists the actions available if the `Filepart` is in status `AwaitingInteraction` or `Error`.
          items:
            $ref: "#/components/schemas/FilepartActionEnum"
        performedActions:
          maxItems: 100
          type: array
          description: A list of performed actions on this `Filepart`.
          items:
            $ref: "#/components/schemas/PerformedAction"
        error:
          $ref: "#/components/schemas/FilepartError"
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentSubtype:
          $ref: "#/components/schemas/DocumentSubtype"
        distribution:
          $ref: "#/components/schemas/Distribution"
        filename:
          maxLength: 1000
          type: string
          description: "If the `Filepart` represents a file, the name of this file."
          example: invoice123.xml
        documentData:
          $ref: "#/components/schemas/FilepartDocumentData"
        presentationUrl:
          maxLength: 1000
          type: string
          description: "The URL used to retrieve a visual presentation of this `Filepart`, if one exists."
          example: https://api.pageroonline.com/file/v2/fileparts/114acacc-3947-4788-b62b-85b5384969aa/presentation
      description: A `Filepart` is a part of a `File` that needs attention in some way. Either because an error has occurred or because the sender is required to perform an action.
    FilepartAction:
      required:
      - action
      type: object
      properties:
        action:
          description: The action to take on the `Filepart`.
          example: RestartWithReplacements
          allOf:
          - $ref: "#/components/schemas/FilepartActionEnum"
        replacements:
          maxItems: 100
          type: array
          description: "Defines the replacements to make. Only applicable if action is `RestartWithReplacements`, in which case it's mandatory."
          items:
            $ref: "#/components/schemas/Replacement"
        reason:
          maxLength: 1000
          type: string
          description: Reason for performing the action.
          example: Buyer reference was invalid.
      description: The action to perform on a `Filepart`.
    FilepartActionEnum:
      type: string
      description: Available actions to take on a `Filepart`. Different actions will be available depending on the filepart's status.
      example: Resume
      enum:
      - Resume
      - Restart
      - RestartWithReplacements
      - Cancel
    Replacement:
      required:
      - errorReference
      - newValue
      type: object
      properties:
        errorReference:
          maxLength: 100
          type: string
          description: The error reference that was provided in the `DocumentError`.
          example: buyerReference
        newValue:
          maxLength: 1000
          type: string
          description: The corrected value.
          example: abc12345
      description: A `Replacement` defines a correction to a specific error in a `DocumentError`.
    FilepartDocumentData:
      type: object
      properties:
        documentIdentifier:
          maxLength: 100
          type: string
          description: "Document identifier for the document. For example Invoice number, Order number etc."
          example: INV2874847
        documentDate:
          maxLength: 10
          type: string
          description: "The date when the document was issued. For example, Invoice date, Order date etc. Expressed in ISO 8601 date-only format."
          format: date
          example: 2024-09-23
        receiverName:
          maxLength: 100
          type: string
          description: "Name of the receiver (as stated in the sent document), if known."
          example: Acme inc.
        dueDate:
          maxLength: 100
          type: string
          description: "Due date, expressed in ISO 8601 date-only format."
          format: date
          example: 2024-10-22
        totalNetAmount:
          maxLength: 100
          type: string
          description: Total Net Amount.
          format: decimal
          example: "200.00"
        totalVatAmount:
          maxLength: 100
          type: string
          description: Total VAT Amount.
          format: decimal
          example: "50.00"
        totalAmount:
          maxLength: 100
          type: string
          description: Total Amount.
          format: decimal
          example: "250.00"
        currency:
          maxLength: 3
          type: string
          description: Currency expressed as a ISO 4217 three-letter code.
          example: EUR
      description: "If a `Filepart` represents a document and it's been possible to extract data from it, some of the data will be available in this object."
    FilepartError:
      type: object
      properties:
        description:
          maxLength: 1000
          type: string
          description: Description of the error.
          example: The document contains an invalid value.
        documentErrors:
          maxItems: 100
          type: array
          description: "A list of document errors that can be resolved, if any. Please see the 'Workflow -> Handle errors' section for further details."
          items:
            $ref: "#/components/schemas/DocumentError"
      description: "If the `Filepart` has status `Error`, this object describes the error."
    Fileparts:
      required:
      - items
      - meta
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/CollectionMetadata"
        items:
          maxItems: 100
          type: array
          items:
            $ref: "#/components/schemas/Filepart"
      description: A collection of `Filepart` resources.
    FilepartStatusEnum:
      type: string
      description: |
        The status of the `Filepart`.

        * **Processing** - The `Filepart` is being processed by Pagero Online.
        When status is `Processing`, more information is available in the
        `processingStatus` property.

        * **AwaitingInteraction** - The `Filepart` is waiting for an action from
        the client. Available actions are shown in the `possibleActions`
        property.

        * **Error** - The `Filepart` has an error which needs to be handled by
        the client. The `error` property contains more information about the
        error.

        * **Cancelled** - The `Filepart` has been cancelled, which means it will
        not be processed or delivered.
      enum:
      - Processing
      - AwaitingInteraction
      - Error
      - Cancelled
    Files:
      required:
      - items
      - meta
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/CollectionMetadata"
        items:
          maxItems: 100
          type: array
          items:
            $ref: "#/components/schemas/File"
      description: A collection of `File` resources.
    MultipleFilepartAction:
      required:
      - action
      - ids
      type: object
      properties:
        ids:
          maxItems: 100
          type: array
          description: A list of filepart ids to perform the specified action on.
          items:
            maxLength: 100
            type: string
            example: 8f3be848-2db9-4302-b233-0e348419d6b6
        action:
          type: string
          description: The action to take on the `Filepart`. The action `RestartWithReplacements` can only be performed on one filepart at a time.
          enum:
          - Resume
          - Restart
          - RestartWithReplacements
          - Cancel
        replacements:
          maxItems: 100
          type: array
          items:
            $ref: "#/components/schemas/Replacement"
        reason:
          maxLength: 1000
          type: string
          description: Reason for the action.
          example: Documents have invalid recipients.
      description: The action to perform on multiple `Filepart`s.
    FilepartActionResult:
      required:
      - action
      - success
      type: object
      properties:
        action:
          maxLength: 100
          type: string
          description: The action which was attempted.
          example: Restart
        success:
          type: boolean
          description: Whether the action was successful.
          example: true
        error:
          maxLength: 1000
          type: string
          description: "Error message in English, if action was not successful."
          example: Not allowed to perform action on filepart.
      description: The result of performing an action on a `Filepart`.
    SendModeEnum:
      title: SendMode
      maxLength: 100
      type: string
      description: |
        The send mode used to send a document. Read more about send modes [here](https://pagero.github.io/additional-functionality/send-modes).
      example: Production
      enum:
      - Production
      - Test
      - Certification
    DocumentType:
      maxLength: 100
      type: string
      description: "The document type, if it is known. Available document types are listed [here](https://pagero.github.io/partners/apis/document-types)."
      example: Invoice
    DocumentSubtype:
      maxLength: 100
      type: string
      description: "The document subtype, if it is known. Available document subtypes are listed [here](https://pagero.github.io/partners/apis/document-types/#document-subtypes)."
      example: Debet
    Distribution:
      maxLength: 100
      type: string
      description: |
        How the document was distributed. Possible values are:
        * **Electronic**
        * **Print**
        * **Email**
        * **None** - Not distributed
      example: Electronic
    User:
      required:
      - id
      type: object
      properties:
        id:
          maxLength: 100
          type: string
          example: e7ba02df-020e-4b8a-93c7-e4540d727f44
        fullName:
          maxLength: 100
          type: string
          example: John Doe
        username:
          maxLength: 100
          type: string
          example: johndoe
        email:
          maxLength: 100
          type: string
          example: john.doe@acme.com
        phone:
          maxLength: 100
          type: string
          example: 555-123456
      description: A `User` represents a user in the Pagero Online system.
    Company:
      required:
      - id
      type: object
      properties:
        id:
          maxLength: 100
          type: string
          example: 2faea0bb-f16f-4de0-8846-2e38bec6f23f
        name:
          maxLength: 1000
          type: string
          description: Company name
          example: Acme inc.
        department:
          maxLength: 1000
          type: string
          description: Company Department
          example: Accounting
      description: A `Company` represents a company in the Pagero Online system.
    AttachmentType:
      maxLength: 100
      type: string
      description: |
        The type of attachment. Available values are:
        * **ProvidedPresentation** - Provided presentation
        * **LegalProvided** - Legal provided
        * **Misc** - Miscellaneous attachment
      example: Misc
      default: Misc
    PerformedAction:
      required:
      - action
      - createTime
      type: object
      properties:
        action:
          $ref: "#/components/schemas/FilepartActionEnum"
        comment:
          maxLength: 1000
          type: string
          description: Comment provided by the user who performed the action.
          example: Cancelled because of invalid content
        createTime:
          maxLength: 100
          type: string
          description: The creation time of the action in ISO 8601 format.
          format: date-time
          example: 2024-09-23T12:41:53Z
        userId:
          maxLength: 100
          type: string
          description: The id of the user who performed the action. Will be empty if action was performed by a support user.
          example: 0c5f458f-b997-427d-b5b5-60a831c753b8
      description: A `PerformedAction` represents an action that has been performed on a `Filepart`.
    ErrorModel:
      required:
      - technicalMessage
      type: object
      properties:
        technicalMessage:
          maxLength: 1000
          type: string
          description: A message in English with a technical explanation of the error.
          example: A technical error description
        errorCode:
          maxLength: 100
          type: string
          description: "An error code for the error. Can be used to provide a more detailed, machine-readable error cause. Possible error codes should be defined for each API resource."
          example: INVALID_PASSWORD
        description:
          maxLength: 1000
          type: string
          description: "A localised description of the error, if applicable."
          example: A localised error description
    SendMode:
      title: SendMode
      maxLength: 100
      type: string
      description: |
        The send mode used to send a document. Read more about send modes [here](https://pagero.github.io/additional-functionality/send-modes).
      example: Production
      enum:
      - Production
      - Test
      - Certification
  responses:
    BadRequestText:
      description: Error message
      content:
        text/plain:
          schema:
            maxLength: 1000
            type: string
            description: Error message
            example: SendMode is missing
    Unauthorized:
      description: Unauthorized
    Forbidden:
      description: The client is not allowed to access the requested resource.
    NotFound:
      description: Not Found
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorModel"
    InternalServerError:
      description: Internal Server Error
  parameters:
    offset:
      name: offset
      in: query
      description: The number of items to skip before returning the results
      schema:
        maximum: 2147483647
        minimum: 0
        type: integer
        format: int32
        default: 0
    limit100:
      name: limit
      in: query
      description: The number of items to return
      required: false
      schema:
        maximum: 100
        minimum: 0
        type: integer
        format: int32
        default: 10
    sendMode:
      name: sendMode
      in: query
      description: "The send mode used to send a document. Read more about send modes here: https://pagero.github.io/additional-functionality/send-modes"
      schema:
        $ref: "#/components/schemas/SendMode"
    documentType:
      name: documentType
      in: query
      description: "The document type. Available document types are listed here: https://pagero.github.io/partners/apis/document-types"
      required: true
      schema:
        $ref: "#/components/schemas/DocumentType"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
