Files
Learn about the files resource
The Files resource represents a customer-related document that is hosted on Digital River's servers. You can use the Files API to upload, retrieve, search for, download, and delete files.
In certain business use cases, you may need to upload a customer's tax documents. As an example, your integration might handle purchases from US-based business customers who use tax certificates. By specifying a file and its purpose and then submitting a
POST/files request, you can perform this document upload.Other files, such as tax invoices and credit memos, are generated by Digital River. You can listen for webhook events that inform you when these types of files are created.
Once created, every File object contains a unique identifier. You can use this identifier to download a file for internal use or create a publicly-accessible link to a document.
To upload a customer's tax documents to our servers, define a file and then submit a create file request.
When defining a file, you're only required to designate a file and its purpose. Providing a name and title, along with specifying a link expiration time, are optional values.
The
file you upload should adhere to the RFC 2388 specification. This specification defines file transfers for the multipart/form-data protocol.The
purpose parameter describes the function of the file. Use the tax_document_customer_upload value when providing Digital River a customer's tax document. This is typically used for tax certificates. The supported file formats are CSV, JPG, PDF, PNG and the maximum upload size is 10 MB.For some orders, Digital River generates a
customer_tax_invoice and customer_credit_memo that you can retrieve in PDF format.In the request, you have the option of sending a
fileName that is suitable for saving to a filesystem as well as a user-friendly title for the document.If you provide a
linkExpiresTime, make sure the value adheres to the date and time format used in the Digital River APIs.In your
POST/files requests, set the Content-Type header to multipart/form-data:POST/files
curl https://api.digitalriver.com/files \
-u <API_key>: \
-d file="@/path/file.jpg" \
-d purpose="tax_document_customer_upload" \
-d fileName="file.png" \
-d title="My 2019 Tax Certificate."
JSON
{
"id": "file_09e2464f-9b4f-482b-ae89-732183c705be",
"createdTime": "2018-04-25T20:36:00Z",
"fileName": "file.png",
"purpose": "tax_document_customer_upload",
"title": "My 2019 Tax Certificate.",
"size": 72334,
"type": "png",
"url": "https://files.digitalriver.com/files/file_17a0cab7-1ff7-478e-99f9-d4e753dec24d/contents",
"liveMode": false
}
Once created, every File object contains a unique identifier that can be used to retrieve, search for and delete a file. The object also contains a non-publicly accessible URL.
File
{
"id": "62e30acb-1c24-40fc-8a98-db8e3d479c78",
"createdTime": "2021-05-24T09:10:49Z",
"fileName": "GCINIE6426071CGB20190000000000284082939532120039586.pdf",
"links": [
{
"id": "7e20a925-32b1-434b-b704-366b19b8afd2",
"createdTime": "2021-05-24T22:11:54Z",
"expired": false,
"expiresTime": "2021-05-26T13:47:13Z",
"liveMode": false,
"url": "https://files-test.digitalriver.com/links/7e20a925-32b1-434b-b704-366b19b8afd2"
}
],
"purpose": "customer_invoice",
"title": "customer invoice",
"size": 35776,
"type": "pdf",
"url": "https://api.digitalriver.com/files/62e30acb-1c24-40fc-8a98-db8e3d479c78/content",
"liveMode": false
}
You can use a File object's unique identifier to retrieve, search for, and delete files. You'll also need it to create a file link that can be shared with customers.
The object may contain an array of publicly-accessible File Links. If no links have been generated, however, then the
links array is not returned.
A file's
size is represented in bytes and its type signifies a format (e.g. pdf, jpg, or png)You can use a File's
url to download a document for internal use. To access a document through the url, you must use your secret (confidential) API key. Since customers won't be able to download the file, you should not share a url with them. If you'd like to provide customers access to a document, create a public link to the file.A request sent with the wrong key returns a
401 Unauthorized response status code.GET /files/{fileId}/content
{
"type": "unauthorized",
"errors": [
{
"message": "An authorization error has occurred."
}
]
}
To share files with customers, create a file link. These publicly accessible links are especially useful for orders that contain Digital River generated tax invoices and credit memos.
Last modified 1mo ago