Files API

Files

Files represent uploaded documents, images, and other attachments in the system. They can be associated with various entities such as commercial documents, journal entries, and other business objects.

Endpoints

Method	Endpoint	Description
GET	/files	List files
POST	/files	Upload a file
GET	/files/{id}	Get a specific file
DELETE	/files/{id}	Delete a file
GET	/files/{id}/download	Download a file

Query Parameters

The GET /files endpoint supports the following query parameters:

Parameter	Type	Required	Description
client_account_id	integer	Yes	Filter by client account ID
type	string	No	Filter by file type
is_active	boolean	No	Filter by active status
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Number of items per page (default: 100)

File Attributes

Attribute	Type	Description
id	integer	The unique identifier of the file
created_at	date	When the file was created
created_by_id	integer	The ID of the user who created the file
updated_at	date	When the file was last updated
updated_by_id	integer	The ID of the user who last updated the file
client_account_id	integer	The ID of the client account
type	string	Type of file (e.g., “FILE”, “VOUCHER”)
file_name	string	Original name of the file
content_type	string	MIME type of the file
channel	string	Upload channel identifier
file_size	integer	Size of the file in bytes
is_active	boolean	Whether the file is active

File URLs

Files can have multiple versions with different URLs:

URL Type	Description
thumbnail_url	URL for a small thumbnail preview (expires in 1 hour)
download_url	URL to download the optimized version (expires in 1 hour)
original_url	URL for the original uploaded file (expires in 1 hour)

Relationships

Relationship	Type	Description
source_file	UploadedFile	The original file this was derived from
target_files	[UploadedFile]	Files derived from this file

Example Response

{
    "id": 1,
    "created_at": "2023-05-10T12:00:00Z",
    "created_by_id": 123,
    "updated_at": "2023-05-10T12:00:00Z",
    "updated_by_id": 123,
    "client_account_id": 1,
    "type": "VOUCHER",
    "file_name": "invoice.pdf",
    "content_type": "application/pdf",
    "channel": "web_upload",
    "file_size": 1024576,
    "is_active": true,
    "thumbnail_url": "https://example.com/thumbnails/invoice.jpg",
    "download_url": "https://example.com/files/invoice-optimized.pdf",
    "original_url": "https://example.com/files/invoice.pdf"
}

Notes

Files can be associated with documents either directly or as attachments
Files can have multiple derivative versions (thumbnails, optimized versions)
All URLs are pre-signed and expire after one hour
The system automatically generates optimized versions and thumbnails for supported file types
Files marked as inactive are not deleted but hidden from normal queries
When uploading a file, you can include base64-encoded content using the content_base64 field (only during upload)