Subscribers
Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants.
File list of available files
This endpoint allows you to retrieve a paginated collection of the files that have been delivered to you.
In order to use this list endpoint:
- Create a Get request to the method’s /files URI and add the query parameter role=subscriber
Example - List Available Files
GET https://api.youserve.nl/fileapi/v1.0/files?role=subscriber
| Parameter Name |
Value |
Description |
| pageIndex |
integer |
The number of the page. (Default:0) |
| pageSize |
integer |
The maximum number of files to return per page. Acceptable values are 1 to 1000, inclusive. (Default: 20) |
| $filter |
string |
A query for filtering the file results. See the “Search for files” guide for the supported syntax. |
| $orderBy |
string |
A query for sorting the file results. See the “Sort files” guide for the supported syntax. |
Example - List Available Files. This example shows how to list the files that have been delivered to you. (role=subscriber) using the sandbox tenant
GET/fileapi/v1.0/files
?role=subscriber
&pageSize=20
&$filter=businessType eq 8000
&$orderBy=uploadDate desc
HTTP/1.1
Host: api.youserve.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 200 OK HTTP status code, along with the paginated collection of the files that are available for you.
By default, only available files are shown. (Not downloaded files). In this case, the “count” field will return the total number of available files considering the query string specified in the parameter $filter. When a file is downloaded, it will not be shown by default anymore in the list, and the “count” field will be decreased to reflect the currently available files.
Example - Response of List Available Files
HTTP/1.1 200
Content-Type: application/json
{
"data": [
{
"downloaded": false,
"fileId": "d92ffb21-7938-488b-a405-bcbc9e0a9696",
"fileName": "sandbox_test_file.xml",
"fileSize": 107,
"tenantId": "sandbox",
"businessType": {
"id": 7101,
"name": "7101"
},
"publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
"uploadDate": "2021-03-25T07:30:23.657Z"
},
{
"downloaded": false,
"fileId": "c5d7438e-5c29-47e7-b518-01e5a39d6711",
"fileName": "sandbox_test_file.txt",
"fileSize": 33,
"tenantId": "sandbox",
"businessType": {
"id": 7101,
"name": "7101"
},
"publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
"uploadDate": "2021-03-25T07:30:23.657Z"
},
{
"downloaded": false,
"fileId": "f0d109df-b933-44f9-92d7-cca525ef120a",
"fileName": "sandbox_test_file.csv",
"fileSize": 76,
"tenantId": "sandbox",
"businessType": {
"id": 7101,
"name": "7101"
},
"publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
"uploadDate": "2021-03-25T07:30:23.657Z"
}
],
"pageIndex": 0,
"pageSize": 20,
"count": 3
}
To search for a specific set of files, use the query string $filter to filter the files to return.
The format of the query string is: field operator values
Where:
-
field specifies the field to search upon.
-
operator specifies the condition for the field.
-
values are the specific values you want to use to filter your search results.
| Field |
Description |
Values |
| uploadDate |
Upload Date according to DateTime OData format |
<DateTime> |
| businessType |
Business Type ID |
<BusinessTypeId> |
| status |
Status |
'available', 'downloaded', 'all' |
| fileName |
Name of the file |
<FileName> |
| Operator |
Description |
| gt |
Great than |
| lt |
Less than |
| ge |
Great than or equal |
| le |
Less than or equal |
| eq |
Equal |
| ne |
Not equal |
| and |
And |
| or |
Or |
| ( |
Open Parenthesis |
| ) |
Close Parenthesis |
| startsWith |
parameter starts with the following substring (only for FileName) |
| endsWith |
parameter ends with the following substring (only for FileName) |
| contains |
parameter contains the following substring (only for FileName) |
| What you want to query |
Query String |
| Files greater than 2020-05-19T08:42:47.400Z |
uploadDate gt 2020-05-19T08:42:47.400Z |
| Files greater than 2020-05-19T08:42:47.400Z and lesser than 2020-05-19T16:42:47.400Z |
uploadDate gt 2020-05-19T08:42:47.400Z and uploadDate lt 2020-05-19T16:42:47.400Z |
| All Files (downloaded and available) |
status eq 'all' |
| Downloaded Files |
status eq 'downloaded' |
| Available Files |
status eq 'available' |
| Files related to BusinessTypeID 7101 |
businessType eq 7101 |
| Files related to BusinessTypeID 7100 or 7101 |
businessType eq 7100 or businessType eq 7101 |
| Downloaded Files related to BusinessTypeID 7100 or 7101 |
status eq 'downloaded' and (businessType eq 7100 or businessType eq 7101) |
| All Files greater than 2020-05-19T08:42:47.400Z related to BusinessTypeID 7101 |
uploadDate gt 2020-05-19T08:42:47.400Z and businessType eq 7101 and status eq 'all' |
| All files with a name that starts with “payroll” |
startsWith(FileName, 'payroll') |
| All files with a name that ends with “holidays“ |
endsWith(FileName, 'holidays') |
| All files with a name that contains “test“ |
contains(fileName, 'test') |
| All files with a name that starts with “payroll“ and a BusinessTypeId 7101 |
startsWith(FileName, 'payroll') and businessType eq 7101 |
To sort the files in an specific order, use the query string $orderBy
The format of the query string is: field modifier
Where:
- field specifies the key to sort. Valid keys are ‘uploadDate’, ‘businessType’, ‘status’, ‘fileName’.
- modifier specifies the order of the sorting (‘asc’ and ‘desc’)
Example usage:
By default, files are sorted by UploadDate desc.
Note: The order in which files need to be downloaded may depend on the type of data and the way the receiving system needs to process it. See examples below:
| What you want query |
Query String |
| Retrieve ‘RST Functie’ files (BT: 101002. Definition of all functions/positions available in Beaufort/YouForce). You would only need the latest file so you can ignore the rest, as each file contains the complete list of functions/positions. |
$filter=businessType eq 101002.
In this case, the $OrderBy query string is not needed, as files are sorted by UploadDate desc by default. |
| Retrieve employee mutations in Bint Harmony Files (BT: 101100). Based on the default settings that Beaufort/YouForce only exports the mutations instead of the full employee dataSet, it is important that you get all the new files and download them from old to new. |
$filter=businessType eq 101100&$orderBy=uploadDate asc |
There are two types of downloads you can perform:
This endpoint allows you to download the files that have been delivered to you.
In order to use this download endpoint:
Example - Download Request
GET https://api.youserve.nl/fileapi/v1.0/files/[fileId]?role=subscriber
Example - Download Available File. This example shows how to download a file that was delivered to you
GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
If the request succeeds, the response includes a 200 OK HTTP status code, along with the bytes of the file.
Example - Successful response of Download Available File
HTTP/1.1 200
<root>
<company>Visma YouServe</company>
<product>File API</product>
<content>Sample File</content>
</root>
These endpoints allow you to download chunks of files that have been delivered to you.
In order to download files by chunks you need to use these endpoints:
File API allows you to download chunks of files that have been delivered to you. This endpoint will be used to check if this capability is in place for the resource.
- Create a Head request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
Example - Check Available File can be downloaded by chunks
HEAD/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 200 OK HTTP status code, along with the headers:
- Content-Length with the size of the requested file
- Accept-Ranges with the range unit accepted
Example - Successful response of Check Available File can be downloaded by chunks
HTTP/1.1 200
Content-Length:107
Accept-Ranges:bytes
File API allows you to download chunks of files that have been delivered to you.
- Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
- Add the HTTP header Accept: application/octet-stream
- Add the HTTP header Range: bytes=firstByte-lastByte where firstByte is the first byte of the chunk you want to download and lastByte is the last one.
Example - Download first 50 bytes of an Available File. This example shows how to download a chunk of a file that was delivered to you
GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
Range: bytes=0-49
If the request succeeds, the response includes a 206 Partial Content HTTP status code, along with the bytes of the chunk and the headers:
- Content-Range with the range retrieved and total file size
- Content-Disposition with the value attachment; filename=name of the file
Example - Successful response of Download first 1024 bytes of an Available File
HTTP/1.1 206
Content-Length: 50
Content-Range: bytes 0-49/107
Content-Disposition:attachment; filename=sandbox_test_file.xml
<root>
<company>Visma YouServe</company>
<product>Fi
When the lower limit of the range is bigger than the last byte of the file, the request will retrieve a 416 error. Example - Request not satisfiable range when Download Range out of Available File bounds
GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
Range: bytes=107-110
The response includes a 416 Range Not Satisfiable HTTP status code, along with the header:
- Content-Range with the accepted range unit and the file size
Example - Response - Error not satisfiable range when Download Range out of Available File bounds
HTTP/1.1 206
Content-Range: bytes */107
{
"correlationId": null,
"message": "Range not satisfiable.",
"errorCode": "416",
"exception": null
}
This endpoint allows to delete a file you are subscribed to. This will not delete the file for everyone, just for the app that is requesting it.
In order to use this endpoint:
- Create a Delete request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
- Add the HTTP header Accept=application/octet-stream
Example - Delete File
DELETE https://api.youserve.nl/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 204 No Content HTTP status code.
If the request succeeds, the response includes a 204 No Content HTTP status code.
Example - Response of Delete File
Visma Denemarken
Visma Finland
Visma Letland
Visma Nederland
Visma Noorwegen
Visma Zweden
Visma Developers & Partners
Visma Latijns-Amerika