Files Service
The `FilesService` provides a set of tools for managing file attachments on Acumatica records. You can use it to download existing files, upload new ones, and retrieve metadata like filenames and comments.
Service Methods
get_file(api_version, file_id)
Retrieves the raw binary content of a file using its unique `file_id` (a GUID). This is useful when you know the specific ID of the file you want to download.
file_id = "9be45eb7-f97d-400b-96a5-1c4cf82faa96" # The GUID of the file
file_bytes = client.files.get_file("24.200.001", file_id)
with open("downloaded_image.jpg", "wb") as f:
f.write(file_bytes)
attach_file_to_record(href_template, filename, content, ...)
Attaches a new file to an existing Acumatica record. This process involves two main steps:
- Fetch the target record: First, you need to get the record you want to attach the file to. The response for this record will contain a special `_links["files:put"]` key, which holds the unique URL template needed for the upload.
- Call `attach_file_to_record`: Use the template from step 1, along with the file's name and its binary content, to perform the upload.
# 1. Fetch the record to get the upload URL template
stock_item = client.records.get_record_by_key_field(
"24.200.001", "StockItem", "InventoryID", "ITEM001"
)
href_template = stock_item["_links"]["files:put"]
# 2. Read the local file and call the attach method
with open("product_image.png", "rb") as f:
file_content = f.read()
client.files.attach_file_to_record(
href_template=href_template,
filename="product_image.png",
content=file_content,
comment="Main product view" # Optional
)
get_file_comments_by...(...)
These helper methods retrieve a list of file metadata objects for a given record, each containing the `id`, `filename`, and `comment`. This is useful when you only need information about the files, not the files themselves. You can fetch by a record's key fields or by its internal `NoteID`.
# Get file info using the sales order's type and number
attachments = client.files.get_file_comments_by_key_field(
"24.200.001",
entity="SalesOrder",
key="SO", # Order Type
value="SO006724" # Order Number
)
for file_info in attachments:
print(f"- {file_info['filename']}")
delete_file(api_version, file_id)
Permanently deletes a file attachment from Acumatica using its unique `file_id`.
# First, you need the ID of the file to delete
file_id_to_delete = "9be45eb7-f97d-400b-96a5-1c4cf82faa96"
client.files.delete_file("24.200.001", file_id_to_delete)
print(f"File {file_id_to_delete} deleted successfully.")