WORKSECTION

Costs

Getting data on time and finanсial costs through API: get_costs

Sample get_costs request

https://your—domain.com/api/admin/v2/?action=get_costs&hash=HASH
Returns data on entered time and financial costs for tasks and subtasks
If page parameter is not specified, costs for all account projects will be received

Optional parameters:
  • page — returns costs of the specified project/task/subtask (see link format for details)
  • datestart and dateend — date range for searching data in DD.MM.YYYY format (inclusive)
  • is_timer — returns only those cost lines, where time is:
    1 — received from the timer
    0 — entered manually
  • filter — additional parameter for searching (see search_tasks for a list of operators to work with data used in filter)

Possible data for use in filter (for the get_costs method):
  • task=TASK_ID — returns data of a specific task/subtask by its ID (can be obtained through get_all_tasks or get_tasks method) (Integer)
  • project=PROJECT_ID — returns data on tasks of a specific project by its ID (can be obtained through get_projects method) (Integer)
  • comment — user comment to a separate cost line (String)
  • dateadd or date_added — date the costs were added in the 'DD.MM. YYYY' format

Returned data on cost lines:
  • id — cost line unique identifier
  • comment — user comment to a separate cost line
  • time — time cost value
  • money — financial cost value
  • date — the date the costs were added
  • is_timer — the way of adding time costs
  • true — received from the timer
    false — entered manually
    • user_from — information about the user, who added an individual cost line
    • task — dataset on a task/subtask, where costs are added (see get_task method for details on returned parameters meaning)
    • total — separate total values for time and financial costs received in the response

Sample JSON response
If the request succeeds, the response will contain ok status and the following data:

{
    "status": "ok",
    "data": [
        {
            "id": "COSTS_ID_1",
            "comment": "COSTS_COMMENT",
            "time": "10:00",
            "money": "100.00",
            "date": "YYYY—MM—DD",
            "is_timer": false,
            "user_from": { "id": "USER_ID",
                "email": "USER_EMAIL",
                "name": "USER_NAME"
            },
            "task": {
                "id": "TASK_ID",
                "name": "TASK_NAME",
                "page": "/project/PROJECT_ID/TASK_ID/",
                "status": "active",
                "priority": "0..10",
                "user_from": { "id": "USER_ID",
                    "email": "USER_EMAIL",
                    "name": "USER_NAME"
                },
                "user_to": { "id": "USER_ID",
                    "email": "USER_EMAIL",
                    "name": "USER_NAME"
                },             "project": {                 "id": "PROJECT_ID",                 "name": "PROJECT_NAME",                 "page": "/project/PROJECT_ID/"             }, 
                "date_added": "YYYY—MM—DD HH:II", "date_start": "YYYY—MM—DD",
                "date_end": "YYYY—MM—DD", "time_end": "HH:II",
                "max_time": 20,
                "max_money": 500, "tags": { "TAG_ID": "TAG_NAME_1", "TAG_ID": "TAG_NAME_2", }
            },
   
        },
        {
            "id": "COSTS_ID_2",
            "comment": "COMMENT_COSTS",
... ... ... }
    ],
    "total": {
        "time": "HH:II",
        "money": "10.01"
    }
}

Getting the total amount of time and financial costs within the project through API: get_costs_total

Sample get_costs_total request

https://your—domain.com/api/admin/v2/?action=get_costs_total&hash=HASH
Returns data on total entered time and financial costs of tasks and subtasks for a specified project
If page parameter is not specified, costs for all account projects will be received

Optional parameters:
  • page — returns costs of the specified project/task/subtask (see link format for details)
  • datestart and dateend — date range for searching data in DD.MM.YYYY format (inclusive)
  • is_timer — returns total amount only for those cost lines, where time is:
    1 — received from the timer
    0 — entered  manually

Sample JSON response
If the request succeeds, the response will contain ok status and the following data:

{
"status": "ok",
"total": {
"time": "HH:II",
"money": "0.00", }
}

Adding time and financial costs in a task or subtask through API: add_costs

Sample add_costs request

https://your—domain.com/api/admin/v2/?action=add_costs&
page=/project/PROJECT_ID/TASK_ID/SUBTASK_ID/&email_user_from=
USER_EMAIL&time=TIME&money=MONEY&date=DD.MM.YYYYY& comment=COMMENT&hash=HASH
Adds a time/financial cost line for a specified task/subtask

Required parameters:
  • page — task/subtask link (see link format for details)
  • email_user_from — user email, who added an individual cost line

Optional parameters:
  • time — time costs in one of the following formats: 0.15 / 0,15 / 0:09
  • money — financial costs in account currency (if it needs to be specified without reference to an hourly rate)
  • is_rate=1 — financial costs are calculated on an hourly rate (money parameter is ignored)
  • comment — comment to a separate cost line
  • date — date the costs were added

Sample JSON response
If the request succeeds, the response will contain ok status and id of the cost line:

{
"status": "ok",
"id": "COSTS_ID"
}

Updating time and financial costs in tasks and subtasks through API: update_costs

Sample add_costs request

https://your-domain.com/api/admin/v2/?action=update_costs&
page=/project/ID_PROJECT/ID_TASK/&id=ID_COSTS
&comment=UPDATED&time=2&is_rate=1&hash=HASH
Updates number of parameters for a specified cost line
All optional parameters are available for updating

Required parameters:
  • page — task/subtask link (see link format for details)
  • id — cost line unique identifier (can be obtained through get_costs method)

Optional parameters:
  • time — time costs in one of the following formats: 0.15 / 0,15 / 0:09
  • money — financial costs in account currency (if it needs to be specified without reference to an hourly rate)
  • is_rate=1 — financial costs are calculated on an hourly rate, if new time value is specified (money parameter is ignored)
  • comment — comment to a separate cost line
  • date — date the costs were added

Parameters unavailable for editing (changing/removing/adding) through the specified method:
  • email_user_from — user email, who added an individual cost line

Sample JSON response
If the request succeeds, the response will contain ok status

{
"status": "ok",
}

Deleting time and financial costs from a task or subtask through API: delete_costs

Sample delete_costs request

https://your-domain.com/api/admin/v2/?action=delete_costs&
page=/project/PROJECT_ID/TASK_ID/&id=COSTS_ID&hash=HASH 
Deletes a specified cost line from a specific task/subtask

Required parameters:
  • page — task/subtask link (see link format for details)
  • id — cost line unique identifier (can be obtained through get_costs method)

Sample JSON response
If the request succeeds, the response will contain ok status

{
"status": "ok",
}

Getting the list of active timers through API: get_timers

Sample get_timers request

https://your—domain.com/api/admin/v2/?action=get_timers&hash=HASH
Returns data on running timers: their ID, start time, timer value and who started them
This request does not require page parameter

Returned data:
  • id — running timer unique identifier
  • time — running timer value at the moment of sending the request
  • date_started — timer start date and time
  • user_from — data on a user, who started the timer
  • task — dataset on a project and task/subtask, where the timer is running (see get_task method for details on returned parameters meaning)

Sample JSON response
If the request succeeds, the response will contain ok status and the following data:

{
    "status": "ok",
    "data": [
        {
            "id": "TIMER_ID",
            "time": "HH:II:SS",
            "date_started": "YYYY—MM—DD HH:II",
            "user_from": { "id": "USER_ID",
                "email": "USER_EMAIL",
                "name": "USER_NAME"
            },
            "task": {
                "id": "TASK_ID",
                "name": "TASK_NAME",
                "page": "/project/PROJECT_ID/TASK_ID/",
                "status": "active",
                "priority": "1",
                "user_from": {
                    "email": "USER_EMAIL",
                    "name": "USER_NAME"
                },
                "user_to": {
                    "email": "USER_EMAIL",
                    "name": "USER_NAME"
                },
                "project": {
                    "id": "PROJECT_ID",
                    "name": "PROJECT_NAME",
                    "page": "/project/PROJECT_ID/"
                }, "text": "TASK_TEXT",
                "date_added": "YYYY—MM—DD HH:II", "date_start": "YYYY—MM—DD",
                "date_end": "YYYY—MM—DD", "time_end": "HH:II",
                "max_time": 20,
                "max_money": 500, "tags": { "TAG_ID": "TAG_NAME_1", "TAG_ID": "TAG_NAME_2" }
            }
        }
    ]
}

Stopping the timer through API: stop_timer

Sample stop_timer request

https://your-domain.com/api/admin/v2/?action=stop_timer& timer=TIMER_ID&hash=HASH
Stops the specified running timer and saves its data
This request does not require page parameter

Required parameters:
  • timer — timer ID (can be obtained through get_timers method)

Sample JSON response
If the request succeeds, the response will contain ok status

{
    "status": "ok"
}
esc
или
Print