Attachments API

The Attachments API provides operations for managing file attachments in CargoXplorer. Attachments can be associated with various entities such as orders, contacts, and equipment.

Types

AttachmentGqlDto

Field	Type	Description
attachmentId	Int!	Unique identifier
attachmentGuid	UUID	Global unique identifier
attachmentType	AttachmentType!	Type of attachment (Picture, Avatar, OtherDocument, etc.)
created	DateTime!	Creation timestamp
createdBy	String!	User who created the attachment
description	String	Optional description
fileName	String!	Original file name
fileUri	String!	Storage URI for the file
lastModified	DateTime!	Last modification timestamp
lastModifiedBy	String!	User who last modified
organizationId	Int!	Organization ID
parentId	String	ID of the parent entity
parentType	AttachmentParentType!	Type of parent entity
previewUri	String	URI for preview image (computed)
thumbnailUri	String	URI for thumbnail image (computed)
presignedFileUri	String	Pre-signed download URL
presignedPreviewUri	String	Pre-signed preview URL
presignedThumbnailUri	String	Pre-signed thumbnail URL
isImage	Boolean	Whether the file is an image
isPdf	Boolean	Whether the file is a PDF
customValues	Map	Custom field values

AttachmentType Enum

Value	Description
Picture	Image file
Avatar	Profile picture
OtherDocument	General document

AttachmentParentType Enum

Value	Description
Order	Order entity
Contact	Contact entity
EquipmentType	Equipment type entity
Commodity	Commodity entity

Queries

getAttachment

Retrieve a single attachment by ID.

query GetAttachment($organizationId: Int!, $attachmentId: Int!) {
  getAttachment(organizationId: $organizationId, attachmentId: $attachmentId) {
    attachmentId
    fileName
    fileUri
    attachmentType
    previewUri
    thumbnailUri
    created
    createdBy
  }
}

Parameters:

Parameter	Type	Required	Description
organizationId	Int!	Yes	Organization ID
attachmentId	Int!	Yes	Attachment ID

getAttachments

Retrieve a paginated list of attachments.

query GetAttachments(
  $organizationId: Int!
  $filter: String
  $search: String
  $orderBy: String
  $skip: Int
  $take: Int
) {
  getAttachments(
    organizationId: $organizationId
    filter: $filter
    search: $search
    orderBy: $orderBy
    skip: $skip
    take: $take
  ) {
    items {
      attachmentId
      fileName
      attachmentType
      parentType
      parentId
      created
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    totalCount
  }
}

Parameters:

Parameter	Type	Required	Description
organizationId	Int!	Yes	Organization ID
filter	String	No	Lucene filter query
search	String	No	Full-text search term
orderBy	String	No	Sort expression (e.g., "created desc")
skip	Int	No	Number of items to skip
take	Int	No	Number of items to return

Filter Examples:

# Filter by attachment type
filter: "attachmentType:Picture"

# Filter by parent type and ID
filter: "parentType:Order AND parentId:12345"

# Filter by file extension
filter: "fileName:*.pdf"

getAllOrderAttachments

Retrieve all attachments related to an order, including order documents and workflow documents.

query GetAllOrderAttachments(
  $organizationId: Int!
  $orderId: Int!
  $search: String
) {
  getAllOrderAttachments(
    organizationId: $organizationId
    orderId: $orderId
    search: $search
  ) {
    items {
      id
      attachmentId
      orderDocumentId
      documentWorkflowId
      fileName
      fileUri
    }
  }
}

Field Resolvers

getPresignedUri

Generate a pre-signed URL for downloading attachments. Available on AttachmentGqlDto.

query GetAttachmentWithPresignedUrl($organizationId: Int!, $attachmentId: Int!) {
  getAttachment(organizationId: $organizationId, attachmentId: $attachmentId) {
    attachmentId
    fileName
    getPresignedUri(uriType: "file", expiresInDays: 1)
  }
}

Parameters:

Parameter	Type	Required	Description
uriType	String!	Yes	Type of URI: "file", "preview", or "thumbnail"
expiresInDays	Int!	Yes	Number of days until URL expires

URI Types:

Type	Description
file	Original file
preview	Large preview image (max 1024px width)
thumbnail	Small thumbnail (300x300 center crop)

getParentOrder

Retrieve the parent order for an attachment. Only available when parentType is Order.

query GetAttachmentWithOrder($organizationId: Int!, $attachmentId: Int!) {
  getAttachment(organizationId: $organizationId, attachmentId: $attachmentId) {
    attachmentId
    fileName
    getParentOrder {
      orderId
      orderNumber
      orderStatus {
        name
      }
    }
  }
}

previewUri / thumbnailUri

These fields return computed paths for preview and thumbnail images. They are automatically generated for supported file types:

• Images: Picture, Avatar attachment types
• PDFs: Any .pdf file

The paths follow a deterministic naming convention:

preview/{organizationId}/{parentType}/{sanitizedFileName}_{attachmentId}_large.jpeg
preview/{organizationId}/{parentType}/{sanitizedFileName}_{attachmentId}_small.jpeg

note

Preview and thumbnail images are generated asynchronously after upload. The URLs will return 404 until generation completes.

Examples

Fetch Attachments for an Order

query OrderAttachments($organizationId: Int!, $orderId: String!) {
  getAttachments(
    organizationId: $organizationId
    filter: "parentType:Order AND parentId:$orderId"
    orderBy: "created desc"
  ) {
    items {
      attachmentId
      fileName
      attachmentType
      description
      created
      createdBy
      previewUri
      thumbnailUri
      getPresignedUri(uriType: "thumbnail", expiresInDays: 1)
    }
    totalCount
  }
}

Get Image Attachments with Previews

query ImageAttachments($organizationId: Int!) {
  getAttachments(
    organizationId: $organizationId
    filter: "attachmentType:Picture OR attachmentType:Avatar"
  ) {
    items {
      attachmentId
      fileName
      previewUri
      thumbnailUri
      getPresignedUri(uriType: "preview", expiresInDays: 7)
    }
  }
}

Download Original File

query DownloadAttachment($organizationId: Int!, $attachmentId: Int!) {
  getAttachment(organizationId: $organizationId, attachmentId: $attachmentId) {
    attachmentId
    fileName
    getPresignedUri(uriType: "file", expiresInDays: 1)
  }
}

The returned getPresignedUri value is a time-limited URL that can be used to download the file directly.