diff --git a/README.md b/README.md index b9e8970..9d5beee 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This is the official Paymo API. * [Filtering](#filtering) * [Including related content](#includes) * [Webhooks](#webhooks) - +* [Leaves Support](#leaves_support) The Paymo is a [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer) API that uses JSON/XML for serialization. @@ -78,6 +78,7 @@ If you exceed the rate limit, you'll get a [429 Too Many Requests](http://tools. * [Clients](sections/clients.md) * [Comments](sections/comments.md) * [Company](sections/company.md) +* [CompaniesDays-Exceptions](sections/companies_days_exceptions.md) * [Discussions](sections/discussions.md) * [Estimate Templates](sections/estimate_templates.md) * [Estimates](sections/estimates.md) @@ -86,6 +87,7 @@ If you exceed the rate limit, you'll get a [429 Too Many Requests](http://tools. * [Invoice Templates](sections/invoice_templates.md) * [Invoice Payments](sections/invoice_payments.md) * [Invoices](sections/invoices.md) +* [Leave Types](sections/leave_types.md) * [Milestones](sections/milestones.md) * [Project Templates](sections/project_templates.md) * [Projects](sections/projects.md) @@ -97,6 +99,7 @@ If you exceed the rate limit, you'll get a [429 Too Many Requests](http://tools. * [Tasks](sections/tasks.md) * [Time Entries](sections/entries.md) * [Users](sections/users.md) +* [Users-Days-Exceptions](sections/users_days_exceptions.md) * [User-Task Assignments](sections/users_tasks.md) @@ -128,6 +131,9 @@ By creating a webhook you create a link between an event in Paymo (e.g. adding a Read more about [webhooks](sections/webhooks.md) + +## [Leaves Support](sections/leaves_support.md) + ## Help us make it better Please tell us how we can make the API better. If you have a specific feature request or if you found a bug, please use GitHub issues. Fork these docs and send a pull request with improvements. diff --git a/sections/companies_days_exceptions.md b/sections/companies_days_exceptions.md new file mode 100644 index 0000000..ff69470 --- /dev/null +++ b/sections/companies_days_exceptions.md @@ -0,0 +1,152 @@ +# Companies Days Exceptions + +Days-exceptions is a date interval that defines a working or a non-working period of time. + +* [Getting days-exceptions intervals](#list) +* [Getting a days-exceptions interval](#get) +* [Creating a days-exceptions interval](#create) +* [Updating a days-exceptions interval](#update) +* [Deleting a days-exceptions interval](#delete) +* [The days-exceptions object](#object) + + + +## Getting days-exceptions intervals + +You can list days-exceptions intervals by making a GET request to: + +* `/api/companiesdaysexceptions`. +* `/api/companiesdaysexceptions?where=is_working=false` for a list of leaves. +* `/api/companiesdaysexceptions?where=is_working=true` for a list of additional working days. + +Example of response: + +```json +{ + "companiesdaysexceptions":[ + { + "id":12, + "date":"2017-06-25", + "end_date":"2017-06-28", + "leave_type_id":2, + "creator_id":23, + "hours_per_day":8, + "status":"approved", + "description":"This is a leave.", + "is_working":false, + "created_on":"2017-06-07T12:10:32Z", + "updated_on":"2017-06-07T12:10:32Z" + }, + { + "id":13, + "date":"2017-06-29", + "end_date":"2017-06-30", + "leave_type_id":4, + "creator_id":21, + "hours_per_day":4, + "status":"pending", + "description":"This is an additional working period.", + "is_working":true, + "created_on":"2017-06-21T18:15:04Z", + "updated_on":"2017-06-21T18:15:04Z" + } + ] +} +``` + + +## Getting a days-exceptions interval + +To get a days-exceptions interval, make a GET request to: + +* `/api/companiesdaysexceptions/[COMPANY_DAYS_EXCEPTIONS_ID]` + +Example response: + +```json +{ + "companiesdaysexceptions": [ + { + "id":12, + "date":"2017-06-25", + "end_date":"2017-06-28", + "leave_type_id":2, + "creator_id":23, + "hours_per_day":8, + "status":"approved", + "description":"This is a leave.", + "is_working":false, + "created_on":"2017-06-07T12:10:32Z", + "updated_on":"2017-06-07T12:10:32Z" + } + ] +} +``` + +You can also [include related content](includes.md) when getting a days-exceptions interval. + + +## Creating a days-exceptions interval + +To create a days-exceptions interval, make a POST request to: + +* `/api/companiesdaysexceptions` + +with the request body containing the new days-exceptions info, as in the examples below: + +```json +{ + "date":"2017-06-25", + "end_date":"2017-06-28", + "is_working":false +} +``` + +If successful, the response will return `201 Created`. The response header `Location` will contain a link for the new days-exceptions interval. The response body will contain the new days-exceptions info as in the **Getting a days-exceptions interval** section. + + +## Updating a days-exceptions interval + +To update an existing days-exceptions, make a POST or PUT request to: + +* `/api/companiesdaysexceptions/[COMPANY_DAYS_EXCEPTIONS_ID]` + +with the request body containing the updated info. You can send only the changed fields. + +Example of request body if you want to change the days-exceptions leave_type_id: + +```json +{ + "leave_type_id": 8 +} +``` + +The response will return `200 OK` and will contain the updated days-exceptions info as in the **Getting a days-exceptions interval** section. + + +## Deleting a days-exceptions interval + +To delete a days-exceptions, make a DELETE request to: + +* `/api/companiesdaysexceptions/[COMPANY_DAYS_EXCEPTIONS_ID]` + +If successful, the response will have a `200 OK` status code. + + +## The days-exceptions object + +A days-exceptions object has the following attributes: + +Attribute|Type|Description +---------|----|----------- +id | integer | _(read-only)_ Unique days-exceptions identifier +date | [datetime](datetime.md) | Interval start date +end_date | [datetime](datetime.md) | Interval end date +leave_type_id | integer | The id of the leave type from the leave_types table (optional) +creator_id | integer | _(read-only)_ The id of the creator +hours_per_day | integer | Number of hours for each day in interval +status | text | Days-exceptions custom status +description | text | Days-exceptions description +is_working | boolean | Defines if a days-exceptions interval is working or it's a leave +created_on | [datetime](datetime.md) | _(read-only)_ Date and time when the days-exceptions was created +updated_on | [datetime](datetime.md) | _(read-only)_ Date and time when the days-exceptions was last updated \ No newline at end of file diff --git a/sections/leave_types.md b/sections/leave_types.md new file mode 100644 index 0000000..c7cb9fd --- /dev/null +++ b/sections/leave_types.md @@ -0,0 +1,123 @@ +#Leave Types + +* [Getting leave-types](#list) +* [Getting a leave-type](#get) +* [Creating a leave-type](#create) +* [Updating a leave-type](#update) +* [Deleting a leave-type](#delete) +* [The leave-type object](#object) + + + +## Getting leave types + +You can list leave types by making a GET request to: + +* `/api/leavetypes` +* `/api/leavetypes?where=paid=true` for a list of paid leave types. + +Example of response: + +```json +{ + "leavetypes": [ + { + "id":1, + "name":"Vacation", + "paid":true, + "created_on":"2017-05-31T14:30:13Z", + "updated_on":"2017-05-31T14:30:13Z" + }, + { + "id":2, + "name":"Sick Leave", + "paid":true, + "created_on":"2017-05-31T14:30:13Z", + "updated_on":"2017-05-31T14:30:13Z" + } + ] +} + + +## Getting a leave-type + +To get a leave-type, make a GET request to: + +* `/api/leavetypes/[LEAVE_TYPE_ID]` + +Example response: + +```json +{ + "leavetypes": [ + { + "id":1, + "name":"Vacation", + "paid":true, + "created_on":"2017-05-31T14:30:13Z", + "updated_on":"2017-05-31T14:30:13Z" + } + ] +} +``` + +You can also [include related content](includes.md) when getting a leave-type. + + +## Creating a leave-type + +To create a leave-type, make a POST request to: + +* `/api/leavetypes` + +with the request body containing the new leave-type info, as in the examples below: + +```json +{ + "name":"Vacation", + "paid":true +} +``` + +If successful, the response will return `201 Created`. The response header `Location` will contain a link for the new leave-type. The response body will contain the new leave-type info as in the **Getting a leave-type** section. + + +## Updating a leave-type + +To update an existing leave-type, make a POST or PUT request to: + +* `/api/leavetypes/[LEAVE_TYPE_ID]` + +with the request body containing the updated info. You can send only the changed fields. + +Example of request body if you want to change the leave-type name: + +```json +{ + "name": "Sick Leave" +} +``` + +The response will return `200 OK` and will contain the updated leave-type info as in the **Getting a leave-type** section. + + +## Deleting a leave-type + +To delete a leave-type, make a DELETE request to: + +* `/api/leavetypes/[LEAVE_TYPE_ID]` + +If successful, the response will have a `200 OK` status code. + + +## The leave-type object + +A leave-type object has the following attributes: + +Attribute|Type|Description +---------|----|----------- +id | integer | _(read-only)_ Unique leave type identifier +name | text | Leave type description +paid | boolean | Leave type payable status +created_on | [datetime](datetime.md) | _(read-only)_ Date and time when the leave-type was created +updated_on | [datetime](datetime.md) | _(read-only)_ Date and time when the leave-type was last updated diff --git a/sections/leaves_support.md b/sections/leaves_support.md new file mode 100644 index 0000000..0d74f3b --- /dev/null +++ b/sections/leaves_support.md @@ -0,0 +1,90 @@ +# Leaves Support + +## Get user annual leave info + +Make sure you've set up the annual leave entitlement for company (POST request to `/api/company/[COMPANY_ID]`) or for an user (POST request to `/api/users/[USER_ID]`) with the body: + +```json +{ + "annual_leave_days_number":21 +} +``` + +Get the user annual leave info by making a POST request to `/api/statsreports` with the body: + +```json +{ + "params":{ + "user_id":76509, + "date_interval":"this_year" + }, + "type": "user_annual_leave_stats" +} +``` + +Example of response: + +```json +{ + "statsreports":[ + { + "info": { + "type":"user_annual_leave_stats", + "params": { + "user_id":76509, + "date_interval":"this_year" + } + }, + "content":[ + { + "user_annual_leave_stats": { + "annual_leave_days_number":21, + "unpaid_leave_days_count":3, + "used_leave_days_count":5 + } + } + ] + } + ] +} +``` + +Available options for date interval are 'this_year' and 'last_year'. + +## Get working days count + +You can find the number of the working days for a user in a interval of time by making a POST request to `/api/statsreports` with the body: + +```json +{ + "params":{ + user_id: 76509, + start_date: "2017-05-06T00:00:00", + end_date: "2017-07-30T00:00:00" + }, + "type": "user_working_days_count" +} +``` + +Example of response: + +```json +{ + "statsreports":[ + { + "info": { + "type":"user_working_days_count", + "params": { + "user_id":76509, + "start_date":"2017-07-06T00:00:00", + "end_date":"2017-07-30T00:00:00" + } + }, + "content":[ + { + "working_days_count":17 + } + ] + } + ] +} \ No newline at end of file diff --git a/sections/users_days_exceptions.md b/sections/users_days_exceptions.md new file mode 100644 index 0000000..1cbefb0 --- /dev/null +++ b/sections/users_days_exceptions.md @@ -0,0 +1,158 @@ +# Users Days Exceptions + +Days-exceptions is a date interval that defines a working or a non-working period of time. + +* [Getting days-exceptions intervals](#list) +* [Getting a days-exceptions interval](#get) +* [Creating a days-exceptions interval](#create) +* [Updating a days-exceptions interval](#update) +* [Deleting a days-exceptions interval](#delete) +* [The days-exceptions object](#object) + + + +## Getting days-exceptions intervals + +You can list days-exceptions intervals by making a GET request to: + +* `/api/usersdaysexceptions?where=user_id=[USER_ID]&&is_working=false` for a list of leaves for a user. +* `/api/usersdaysexceptions?where=date<=[INTERVAL_END_DATE]&&end_date>=[INTERVAL_START_DATE]` for a list o all days_exceptions from an interval. + +You have to specify at least one `where` condition: `user_id` or ( `date` and `end_date` ) + +Example of response: + +```json +{ + "usersdaysexceptions":[ + { + "id":12, + "date":"2017-06-25", + "end_date":"2017-06-28", + "user_id": "11", + "leave_type_id":2, + "creator_id":23, + "hours_per_day":8, + "status":"approved", + "description":"This is a leave.", + "is_working":false, + "created_on":"2017-06-07T12:10:32Z", + "updated_on":"2017-06-07T12:10:32Z" + }, + { + "id":13, + "date":"2017-06-29", + "end_date":"2017-06-30", + "user_id": "12", + "leave_type_id":4, + "creator_id":21, + "hours_per_day":4, + "status":"pending", + "description":"This is an additional working period.", + "is_working":true, + "created_on":"2017-06-21T18:15:04Z", + "updated_on":"2017-06-21T18:15:04Z" + } + ] +} +``` + + +## Getting a days-exceptions interval + +To get a days-exceptions interval, make a GET request to: + +* `/api/usersdaysexceptions/[USER_DAYS_EXCEPTIONS_ID]` + +Example response: + +```json +{ + "usersdaysexceptions": [ + { + "id":12, + "date":"2017-06-25", + "end_date":"2017-06-28", + "user_id": 21, + "leave_type_id":2, + "creator_id":23, + "hours_per_day":8, + "status":"approved", + "description":"This is a leave.", + "is_working":false, + "created_on":"2017-06-07T12:10:32Z", + "updated_on":"2017-06-07T12:10:32Z" + } + ] +} +``` + +You can also [include related content](includes.md) when getting a days-exceptions interval. + + +## Creating a days-exceptions interval + +To create a days-exceptions interval, make a POST request to: + +* `/api/usersdaysexceptions` + +with the request body containing the new days-exceptions info, as in the examples below: + +```json +{ + "date":"2017-06-25", + "end_date":"2017-06-28", + "user_id": 21, + "is_working":false +} +``` + +If successful, the response will return `201 Created`. The response header `Location` will contain a link for the new days-exceptions interval. The response body will contain the new days-exceptions info as in the **Getting a days-exceptions interval** section. + + +## Updating a days-exceptions interval + +To update an existing days-exceptions, make a POST or PUT request to: + +* `/api/usersdaysexceptions/[USER_DAYS_EXCEPTIONS_ID]` + +with the request body containing the updated info. You can send only the changed fields. + +Example of request body if you want to change the days-exceptions leave_type_id: + +```json +{ + "leave_type_id": 8 +} +``` + +The response will return `200 OK` and will contain the updated days-exceptions info as in the **Getting a days-exceptions interval** section. + + +## Deleting a days-exceptions interval + +To delete a days-exceptions, make a DELETE request to: + +* `/api/usersdaysexceptions/[USER_DAYS_EXCEPTIONS_ID]` + +If successful, the response will have a `200 OK` status code. + + +## The days-exceptions object + +A days-exceptions object has the following attributes: + +Attribute|Type|Description +---------|----|----------- +id | integer | _(read-only)_ Unique days-exceptions identifier +date | [datetime](datetime.md) | Interval start date +end_date | [datetime](datetime.md) | Interval end date +user_id | integer | The id of the user for which an days-exceptions interval is added +leave_type_id | integer | The id of the leave type from the leave_types table (optional) +creator_id | integer | _(read-only)_ The id of the creator +hours_per_day | integer | Number of hours for each day in interval +status | text | Days-exceptions custom status +description | text | Days-exceptions description +is_working | boolean | Defines if a days-exceptions interval is working or it's a leave +created_on | [datetime](datetime.md) | _(read-only)_ Date and time when the days-exceptions was created +updated_on | [datetime](datetime.md) | _(read-only)_ Date and time when the days-exceptions was last updated \ No newline at end of file