**\[GET\]/api/v1/annotations/{id}**
**Response:** Annotation. ### Header Header used on this API are those taken from [header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital) `Content-type` is accepted in `application/json` ### Query Parameters Parameters used to make a successful request. - **id**: Unique identifier associated with the requested annotation. (***required***) ### Body No body is needed to make this request. ### Response ##### On successful response If successful, the **API** responds with HTTP code **200(OK)** with the following body: ```JSON { "id": "string", "type": "string", "text": "string", "classification": "string", "referencingDate": "string", "referencePeriod": "string", "referenceType": "string", "referenceIds": [ "string" ], "deleted": true, "ownership": { "type": "WS", "identifier": "string" }, "itemClassifier": "string", "insertedBy": "string", "insertedAt": "2022-10-28T13:01:00.754Z", "modifiedAt": "2022-10-28T13:01:00.754Z" } ``` - **id**: unique identifier of the annotation - **type**: specifies the annotation type. - **text**: contains information about the annotation. Depending on the type, the information contained can be: - **note text**: the text value, in case the annotation is of type **NOTE** - **folder name**: the name of the folder, in case the annotation is of type **FOLDER** - **classification**: the classification of the annotation - **referencing\_date**: the referencing date - **reference\_period:** the year of reference - **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE** - **reference\_ids**: the ids of the related documents - **deleted**: specifies if the annotation is deleted or not - **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: - **type**: it can be **WS** or **ITEM** - **identifier**: the item identifier - **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY** - **inserted\_by**: the name of the creator of the annotation - **inserted\_at**: the timestamp of the annotation creation - **modified\_at**: the timestamp of the last edit of the annotation ##### On error response In the event of an error, the **API** responds with a body **JSON** with the following format: ```JSON { "code": "string", "timestamp": "2022-10-28T13:01:00.754Z", "message": "string", "subErrors": [ {} ] } ``` - **code**: A string representation of the HTTP error code, linked with the returned http error - **timestamp**: Date and time of the answer, expressed as a string. - **message**: Message expressing error. Possible errors are: - **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters). - **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired). - **403**: The provided token is valid, but the user is not authorized to perform the operation. - **404**: No annotation found with the given id - **500**: An unexpected error occurred. # Create annotation This API is responsible for creating an annotation.**\[POST\]/api/v1/annotations**
**Response:** The id of the newly created annotation. ### Header Header used on this API are those taken from [header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital) `Content-type` is accepted in `application/json` ### Query Parameters No query parameters are needed to make this request. ### Body ```JSON { "id": "string", "type": "string", "text": "string", "classification": "string", "ownership": { "type": "WS", "identifier": "string" }, "referencing_date": "string", "reference_period": "string", "reference_type": "string", "reference_ids": [ "string" ], "item_classifier": "string", "inserted_by": "string" } ``` - **id**: the identifier of the annotation, if not specified a random UUID will be generated instead - **type**: specifies the annotation type. - **text**: contains information about the annotation. Depending on the type, the information contained can be: - **note text**: the text value, in case the annotation is of type **NOTE** - **folder name**: the name of the folder, in case the annotation is of type **FOLDER** - **classification**: the classification of the annotation - **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: - **type**: it can be **WS** or **ITEM** - **identifier**: the item identifier - **referencing\_date**: the referencing date - **reference\_period:** the year of reference - **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE** - **reference\_ids**: the ids of the related documents - **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY** - **inserted\_by**: the name of the creator of the annotation ### Response ##### On successful response If successful, the **API** responds with HTTP code **200(OK)** with the following body: ```JSON { "id": "string" } ``` - **id**: the unique identifier of the annotation ##### On error response In the event of an error, the **API** responds with a body **JSON** with the following format: ```JSON { "code": "string", "timestamp": "2022-10-28T13:01:00.754Z", "message": "string", "subErrors": [ {} ] } ``` - **code**: A string representation of the HTTP error code, linked with the returned http error - **timestamp**: Date and time of the answer, expressed as a string. - **message**: Message expressing error. Possible errors are: - **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters). - **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired). - **403**: The provided token is valid, but the user is not authorized to perform the operation. - **500**: An unexpected error occurred. # Update annotation This API is responsible for updating an annotation.**\[PATCH\]/api/v1/annotations/{id}**
**Response:** The id of the updated annotation. The update operation is only available to the user who created the annotation. ### Header Header used on this API are those taken from [header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital) `Content-type` is accepted in `application/json` ### Query Parameters Parameters used to make a successful request. - **id**: Unique identifier associated with the requested annotation. (***required***) ### Body ```JSON { "type": "string", "text": "string", "classification": "string", "ownership": { "type": "WS", "identifier": "string" }, "referencing_date": "string", "reference_period": "string", "reference_type": "string", "reference_ids": [ "string" ], "item_classifier": "string" } ``` Each of the fields are optional; only the field included in the request will be updated on the database. - **type**: specifies the annotation type. - **text**: contains information about the annotation. Depending on the type, the information contained can be: - **note text**: the text value, in case the annotation is of type **NOTE** - **folder name**: the name of the folder, in case the annotation is of type **FOLDER** - **classification**: the classification of the annotation - **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: - **type**: it can be **WS** or **ITEM** - **identifier**: the item identifier - **referencing\_date**: the referencing date - **reference\_period:** the year of reference - **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE** - **reference\_ids**: the ids of the related documents - **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY** ### Response ##### On successful response If successful, the **API** responds with HTTP code **200(OK)** with the following body: ```JSON { "id": "string" } ``` - **id**: the unique identifier of the annotation ##### On error response In the event of an error, the **API** responds with a body **JSON** with the following format: ```JSON { "code": "string", "timestamp": "2022-10-28T13:01:00.754Z", "message": "string", "subErrors": [ {} ] } ``` - **code**: A string representation of the HTTP error code, linked with the returned http error - **timestamp**: Date and time of the answer, expressed as a string. - **message**: Message expressing error. Possible errors are: - **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters). - **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired). - **403**: The provided token is valid, but the user is not authorized to perform the operation. - **404**: No annotation found with the given id. - **500**: An unexpected error occurred. # Update references This API is responsible for updating an annotation`s references.**\[PUT\]/api/v1/annotations/{id}/{operation}**
**Response:** The id of the updated annotation. ### Header Header used on this API are those taken from [header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital) `Content-type` is accepted in `application/json` ### Query Parameters Parameters used to make a successful request. - **id**: Unique identifier associated with the requested annotation. (***required***) - **operation**: it can be **ATTACH** in case there need to be added references and **DETACH** in case the references need to be removed. (***required***) ### Body ```JSON { "reference_ids": [ "string" ] } ``` - **reference\_ids**: the ids of the related documents to be added or removed ### Response ##### On successful response If successful, the **API** responds with HTTP code **200(OK)** with the following body: ```JSON { "id": "string" } ``` - **id**: the unique identifier of the annotation ##### On error response In the event of an error, the **API** responds with a body **JSON** with the following format: ```JSON { "code": "string", "timestamp": "2022-10-28T13:01:00.754Z", "message": "string", "subErrors": [ {} ] } ``` - **code**: A string representation of the HTTP error code, linked with the returned http error - **timestamp**: Date and time of the answer, expressed as a string. - **message**: Message expressing error. Possible errors are: - **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters). - **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired). - **403**: The provided token is valid, but the user is not authorized to perform the operation. - **404**: No annotation found with the given id. - **500**: An unexpected error occurred. # Delete annotation This API is responsible for soft deleting an annotation.**\[DELETE\]/api/v1/annotations/{id}**
**Response:** The id of the deleted annotation. ### Header Header used on this API are those taken from [header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital) `Content-type` is accepted in `application/json` ### Query Parameters Parameters used to make a successful request. - **id**: Unique identifier associated with the annotation to be deleted. (***required***) ### Body No body is needed to make this request. ### Response ##### On successful response If successful, the **API** responds with HTTP code **200(OK)** with the following body: ```JSON { "id": "string" } ``` - **id**: the unique identifier of the deleted annotation ##### On error response In the event of an error, the **API** responds with a body **JSON** with the following format: ```JSON { "code": "string", "timestamp": "2022-10-28T13:01:00.754Z", "message": "string", "subErrors": [ {} ] } ``` - **code**: A string representation of the HTTP error code, linked with the returned http error - **timestamp**: Date and time of the answer, expressed as a string. - **message**: Message expressing error. Possible errors are: - **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters). - **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired). - **403**: The provided token is valid, but the user is not authorized to perform the operation. - **404**: No annotation found with the given id. - **500**: An unexpected error occurred. # Search annotations This API is responsible for searching annotations.**\[POST\]/api/v1/annotations/search**
**Response:** A list of the requested annotations. ### Header Header used on this API are those taken from [header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital) `Content-type` is accepted in `application/json` ### Query Parameters No query parameters are needed to make this request. ### Body ```JSON { "limit": "integer", "from": "integer", "ownership": { "type": "WS", "identifier": "string" }, "sort": { "name": "CREATED", "order": "ASC" }, "type": "string", "reference_ids": [ "string" ], "show_deleted": true, "search_words": "string" } ``` - **limit**: limits the number of annotations in the response. The default value is 100. - **from**: specifies the value of the field next from a pagination call. The default value is 0. - **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: - **type**: it can be **WS** or **ITEM** - **identifier**: the item identifier - **sort**: specifies the sorting order. The **order** field specifies if the sorting has to be in ascending (**ASC**) or descending (**DESC**) order. The other field, **name**, can have the following values: - **CREATED**: sorting on the creation date. - **UPDATED**: sorting on the last modified date. - **ALPHABETICAL**: sorting on alphabetical order. - **type**: specifies the annotation type, **FOLDER** or **NOTE**. - **reference\_ids**: the ids of the related documents - **show\_deleted**: shows the deleted annotations if set to true. Default value is false. - **search\_words**: search for terms in the text field of the entity. The default value is all. ### Response ##### On successful response If successful, the **API** responds with HTTP code **200(OK)** with the following body: ```JSON { "count": "integer", "data": [ { "id": "string", "type": "string", "text": "string", "classification": "string", "referencingDate": "string", "referencePeriod": "string", "referenceType": "string", "referenceIds": [ "string" ], "deleted": true, "ownership": { "type": "WS", "identifier": "string" }, "itemClassifier": "string", "insertedBy": "string", "insertedAt": "2022-10-31T15:02:44.115Z", "modifiedAt": "2022-10-31T15:02:44.115Z" } ] } ``` - **count**: the number of the annotations returned by the search that fulfill the search filters. - **data**: an list containing all the annotations that fulfill the search filters. The elements inside the **data** list contain the following fields: - **id**: unique identifier of the annotation, in UUID format - **type**: specifies the annotation type. It can have the following values: - **NOTE** - **FOLDER** - **text**: contains information about the annotation. It has a maximum length of 1000 characters. Depending on the type, the information contained can be: - **note text**: the text value, in case the annotation is of type NOTE - **folder name**: the name of the folder, in case the annotation is of type FOLDER - **classification**: it can have the following possible values: - **PERSONALIZZATO** - **BANCA** - **BILANCIO** - **DICHIARAZIONI** - **CONTENZIOSO** - **referencing\_date**: the referencing date - **reference\_period:** the year of reference - **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE** - **reference\_ids**: the ids of the related documents - **deleted**: specifies if the annotation is deleted or not - **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: - **type**: it can be **WS** or **ITEM** - **identifier**: the item identifier - **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY** - **inserted\_by**: the name of the creator of the annotation - **inserted\_at**: the timestamp of the annotation creation - **modified\_at**: the timestamp of the last edit of the annotation ##### On error response In the event of an error, the **API** responds with a body **JSON** with the following format: ```JSON { "code": "string", "timestamp": "2022-10-28T13:01:00.754Z", "message": "string", "subErrors": [ {} ] } ``` - **code**: A string representation of the HTTP error code, linked with the returned http error - **timestamp**: Date and time of the answer, expressed as a string. - **message**: Message expressing error. Possible errors are: - **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters). - **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired). - **403**: The provided token is valid, but the user is not authorized to perform the operation. - **500**: An unexpected error occurred.