Lineitems::attachments

Manage attachments attached to a LineItem

File/document vs Attachment vs Versions

On Winddle, a file (also called ‘document’ in the most general case) is:

Attached to something else (Product, Checkpoint, etc.), hence the name “attachment” used hereafter
A collection of versions: every attachment has many versions, one of them being the “current version” (the last one)

As such, the “attachment” is merely a container for versions, as well as the object to which comments can be attached to when discussing a file.

Resource formats

This endpoint (on create/update) is one of the few that will respond to a HTML request as a HTML multipart form is the only way to push an attachment directly to Winddle. If HTML multipart isn’t an option, then Winddle also offers uploading documents using the content encoded as a Base 64 string or using a remote url (winddle will then download the attachment and store it, as if it had been uploaded - it’s a complete copy and there are no differences with other type of attachment upload).

Note that although the request can be in HTML (Content-Type: multipart/form-data), the responses will be in JSON or XML (accept:application/json, text/javascript, /;).

Storage

An attachment is a Winddle object, and so are the versions, however, versions have a “storage” field which defines where the file is actually stored. For an external storage, the external url is also sent in the same url field, and an additional field, storage_id is given for reference.

All the versions of an attachment do not need to be on the same storage - it’s possible to mix and match.

Winddle currently only support Google Drive as external storage.

Attachment base fields

Most of those fields are set by Winddle automatically after the upload and are actually version fields for the latest version created for this attachment.

Name	Description
id	Integer (unique)
source_id	String (max 255 chars)
storage	String
name	String, visible in interface
filename	String, original filename
created_at	Datetime
updated_at	Datetime
label	String, for virtual folders
size	Integer, size in bytes
url	Download url for attachment or external url for external storage
mime_type	String

Some fields are only available if the attachment is an image:

Name	Description
px40	Url to 40px cropped version
px75	Url to 75px cropped version
px150	Url to 150px cropped version
nc1000	Url to 100px non-cropped version

This field is only available when the version is stored outside of winddle:

Name	Description
external_id	String (meaning depends on `storage`)

Attachment associated resources

Owner

The owner is the user who first created the attachment. Its basic information are always returned in any response containing attachments, under the key owner.

Versions

Full array of versions linked to the attachment. The last one is the “current” one and gives all of its values to the attachment itself. In most cases, the array under the key versions can thus be completely ignored.

Comments

All attachments on Winddle can be commented on (although this feature isn’t always visible in the interface). All the posted comments are under the key comments.

Supported Formats

JSON XML

>>>

GET /api/v1/line_items/:line_item_id/attachments

Retrieve attachments for a given LineItem

Accessible to any partner of the line item.

>>>

GET /api/v1/line_items/:line_item_id/attachments/:id

Retrieve one attachment for a given LineItem

Accessible to any partner of the line item.

>>>

POST /api/v1/line_items/:line_item_id/attachments

Create a new attachment for a given LineItem

This operation is authorized to any partner of the line item.

On Winddle, attachments are only containers for versions, which contain the actual file. Although versions_attributes is an array, only one version of a datafile can be created / request - the array should only contain one element describing the version.

There are 3 ways to upload an attachment on Winddle (in order of priority if more than one provided):

By providing a base64 data string that represents the file
By providing a remote url (public)
By providing the file directly in the body of the multipart request

Here are the fields for the elements in the versions_attributes array:

Name	Type
note	Note for that version
base64_data	File content encoded in base 64
remote_attached_url	String (unique, max 255 chars)
attached	File (HTML multipart form)

Examples

POST /line_items/:line_item_id/attachments

{
  name: "MyFile.png",
  versions_attributes: [{
    note: "Direct upload from our FTP",
    remote_attached_url: "ftp://www.mycompany.com/images/my_file.png"
  }]
}

Params

Param name	Description
source_id optional	ID in Customer’s source system (optional, max 255 char.) Must be a String
name optional	A name for the attachment. If no name provided, filename will be used Must be a String
label optional	The ‘folder’ (virtual) for his attachment Must be a String
versions_attributes optional	an array of versions An array of versions. Here is a list version attributes * base64_data allow you to submit an image as a base64 string * attached a file, any kind of format * remote_attached_url an url to find a file. the file is downloaded asynchronously. Please observe that * you can only submit a version at a time * you should only use one of the three attributes

>>>

PUT /api/v1/line_items/:line_item_id/attachments/:id

Update an attachment for a given LineItem - including adding a new version

Also see LineItems::Attachments#create.

This operation is authorized to any partner of the line item.

Existing versions cannot be updated, they can only be deleted.

Examples

This will create a new version for the attachment with the provided :id.

PUT /line_items/:line_item_id/attachments/:id

{
  versions_attributes: [{
    note: "Direct upload from our FTP",
    remote_attached_url: "ftp://www.mycompany.com/images/my_file.png"
  }]
}

Params

Param name	Description
source_id optional	ID in Customer’s source system (optional, max 255 char.) Must be a String
name optional	A name for the attachment. If no name provided, filename will be used Must be a String
label optional	The ‘folder’ (virtual) for his attachment Must be a String
versions_attributes optional	an array of versions An array of versions. Here is a list version attributes * base64_data allow you to submit an image as a base64 string * attached a file, any kind of format * remote_attached_url an url to find a file. the file is downloaded asynchronously. Please observe that * you can only submit a version at a time * you should only use one of the three attributes

>>>

DELETE /api/v1/line_items/:line_item_id/attachments/:id

Delete the attachment and all its versions/comments

This operation is authorized to any line item managers and/or the original owner of this attachment.

>>>

PATCH /api/v1/line_items/:line_item_id/attachments/:id/move_to_checkpoint

Move an attachment from this checkpoint to another

The target checkpoint must belong to the same line item than the attachment is currently attached to.

This operation is authorized to any line item managers and/or the original owner of this attachment.

Params

Param name	Description
target_id optional	Target checkpoint id Must be a Integer