SendDocumentsToPlant - REST API
Overview
This is an upgraded version of SendDocumentsToPlant method which support multi-part file upload as well as large file upload.
Rest Endpoint
Staging environment - testwebservice2.boligmappa.no/FileUpload
Production environment - webservice2.boligmappa.no/FileUpload
Request Parameters
Request Header
| Parameter | Type | Mandatory / Optional | Description |
|---|---|---|---|
| userName | String | Mandatory | Username of the company user |
| password | String | Mandatory | Password of the company user |
Request Body
| Parameter | Type | Mandatory / Optional | Maximum character length/limit | Description |
|---|---|---|---|---|
| applicationName | String | Mandatory | Should be less than or equal to 10 characters | The name of the integration partner |
| documentData | String | Mandatory | N/A | Json body as outline below (refer the sample) |
| files | File | Mandatory - if URL is not available | Files to be uploaded |
documentData model
| Parameter | Type | Mandatory/Optional | Description |
|---|---|---|---|
| PlantId | Long | Mandatory | Id of the plant (Building/Property) to where the documents should be uploaded |
| PropertyOwnerEmail | String | Optional | A notification is sent to the given email address when a document is uploaded to the property |
| Documents | List<DocumentInput> | Mandatory | List of documents to be uploaded |
DocumentInput model
Following are mandatory properties for document input model,
- FileName – This should be the name of the attached file (ex: testDoc.pdf)
- DocumentTypeId
- ProfessionId
- BuildingId
- URL – This is mandatory if file is not attached
- Title
- Order Number
Request - documentData sample
{
"PlantId":6658,
"PropertyOwnerEmail":"abc@email.com",
"Documents":[
{
"FileName":"test.zip",
"DocumentTypeId":6,
"Url":"",
"Title":"File1",
"OrderNumber":"123",
"ProfessionId":1,
"BuildingId":3269,
"RoomIds":[]
}]
}
Response
| Status | Type | Description |
|---|---|---|
| Success | SendDocumentsToPlantOutput | SendDocumentsToPlantOutput model in JSON format |
| Fail | JSON object | JSON string with Error Code and Message |
Response - Success
Parameter | Type | Description |
|---|---|---|
| Statuses | List<DocumentUploadStatus> | Document response model List |
| SummaryDocument | string | Url of the summary document, This document contains urls for all the successfully sent documents, plant details and company details. This document will be created only if the relevant plant is owned by a company. |
Response - Fail
Parameter | Type | Description |
|---|---|---|
| Code | String | Error code |
| Message | String | Description of the error |
Response Sample
- Success
{
"Statuses": [
{
"DocumentTitle": "Test 01",
"DocumentId": 0,
"UploadStatusCode": 1,
"ErrorCode": 0
},{
"DocumentTitle": "Test 02",
"DocumentId": 0,
"UploadStatusCode": 0,
"ErrorCode": 133
},],
"SummaryDocument": null
}
NOTE: Success response contain Statuses of each individual file. If document upload is success, then UploadStatusCode will be 1 else UploadStatusCode will be 0 along with the ErrorCode.
- Fail
{
"Code":"111",
"Message":"plantId does not exist for your company"
}
Exceptions
| Error Code | Description |
|---|---|
111 | plantId does not exist for your company |
112 | There is no document to upload |
113 | One or more mandatory fields have not been supplied in input |
114 | File name contains invalid charactor(s) |
115 | Given ProfessionId(s) are not valid |
116 | Invalid DocumentTypeId |
123 | An exception occurred while processing your request |
126 | File extension is not specified |
133 | Url or Data must be provided to create a document file |
136 | Provided Url is invalid |
138 | applicationName length has exceeded the maximum character limit allowed (10) |
146 | The applicationName is not set |
165 | The given profession is not registered to your company |
167 | You are not authorized to use this web method |
179 | One or more of the attached RoomIds do not belong to the given plant |
180 | One of more of the attached DeviceIds do not belong to the given plant |
181 | To tag a document to a room or a device, the given plant needs to be connected to a property |
182 | One or more of the attached BuildingIds do not belong to the given plant |
203 | BuildingId of the document should be either 0 or match the building plant provided |
217 | An error occurred while sending the notification mail to the user |
218 | The PropertyOwnerEmail provided is not valid |
310 | One or more input chapter tags are invalid |
311 | Professionals are not allowed to tag Chapter Tag Id 1 (Generell brukerveiledning bolig) |
330 | Document description has exceeded the maximum character limit allowed (360) |
331 | Document title has exceeded the maximum character limit allowed (260) |
332 | Document filename has exceeded the maximum character limit allowed (260) |
333 | OrderNumber has exceeded the maximum character limit allowed (50) |
335 | Either DocumentType or ChapterTag is mandatory |
Note: The above error codes are custom error codes defined by Boligmappa. We are using REST endpoints for file upload. Therefore in the particular endpoint, we use HTTP error codes.
Example Scenario:
Uploading a file through SendDocumentsToPlant.
Response HTTP status code 401 Unauthorized Access (In the above table, 401 is defined for "tenant does not exist", which is not related to the file upload scenario here.)