File Management

The UploadFileToEntity mutation allows you to directly upload a file and associate it with a business entity such as a Customer, Supplier, or AccountingEntry.

The file is streamed directly through the GraphQL mutation using the Upload scalar type, following the GraphQL multipart request specification.

The Files query returns a list of information about files previously uploaded using the uploadFileToEntity mutation, or generated/uploaded directly from Sage Active.
For each file, details such as fileName, mimeType, uploadDate, size, and related entity information are provided.
It supports advanced filtering, sorting, and pagination on fields such as entityType, entityId, businessDate, and fileName.

This query is useful for multiple scenarios:

• Retrieving all document records linked to business entities (e.g., all invoices attached to an accounting entry)
• Retrieving information about a specific file by its id (to check metadata or availability)
• Checking whether an uploaded file has been fully processed and is safe to use (via id filter, useful right after an upload)
• Listing files generated by an filesExport request

As each uploaded file undergoes an antivirus scan, the query response normally includes only processed and safe files.

• Files that are still being processed (pending upload submission or antivirus scan results) or that have been rejected as infected are excluded from the response.
• Exception: when filtering explicitly by id, the query may also return files that are still being processed, allowing you to check the status of a recently uploaded file.

If explicitly requested, each file entry can include short-lived access paths:

• downloadPath: a temporary relative path to download the file.
• previewPath: a temporary relative path to preview the file content in a browser.

These short paths are valid only for a limited time and should be used promptly after retrieval.

The File Download by Id page illustrates a common use case of the files query.
It focuses on scenarios where you already know the file ID (for example, obtained from a previous files query) and you need to retrieve short-lived link paths (downloadPath and previewPath) to access the file.

This pattern is typically used when:

• You first list files with metadata only (without requesting link paths).
• Later, when a user selects a file to open, you run a new files query filtered by its ID to get a fresh valid link.

The returned link paths are temporary and must be consumed quickly:

• downloadPath always forces download of the file (due to the Content-Disposition: attachment header).
• previewPath displays the file inline when possible, with optional HTML previews for .csv, .xml, and .txt.

The FilesExport query initiates the generation of an export archive for files matching the specified filters.
It triggers the creation of one or more ZIP files (each limited to 65MB) and an accompanying index.csv file describing the contents.

The response itself does not return the download links.
Instead, it provides the status of the export request (ACCEPTED or NO_MATCH).
Once the request is accepted and processing is complete, the generated artifacts can be retrieved using the files query with the filter filesExport: { eq: true }.
This query will return short-lived download links (downloadPath) for the index.csv and the exported ZIP packages.

This mechanism is ideal for exporting documents by customer, supplier, accounting entry, or for compliance and audit purposes.

All filtering options and restrictions are identical to those supported by the files query.