В вашем браузере отключены Cookie. Для корректного отображения сайта их необходимо включить.
IE version

Введение

Pyrus API открывает приложениям доступ к задачам и проектам пользователей системы. Наша цель – максимально облегчить любую разработку, использующую функции Pyrus в сфере управления бизнес-процессами, не жертвуя при этом безопасностью. Выполните два простых условия перед тем, как начинать программировать:

1. Зарегистрируйте приложение в Pyrus и получите Client ID и Client Secret, или используйте тестовую пару – demokey и demosecret, чтобы ознакомиться с Pyrus API без регистрации. Эти идентификаторы необходимы для получения специального AccessToken(access_token), который требуется для безопасного вызова методов Pyrus API.

2. Пользователи вашего приложения должны быть одновременно пользователями Pyrus.

Вот и все – можно вызывать методы API, используя точки входа нашего веб-сервиса и токены OAuth для авторизации.

Авторизация

Pyrus API использует OAuth 2.0 протокол для аутентификации и авторизации. Вызовы должны выполняться через SSL (https://).

Для вызова методов необходимы:

  • Client ID идентифицирующий Ваше приложение.
  • AccessToken(access_token), используемый для верификации и аутентификации запросов.

Pyrus поддерживает 2 вида авторизации:

  • Авторизация для веб-приложения. Этот вариант является предпочтительным. Его следует использовать в случае, если ваше приложение интерактивно и может показать пользователю веб-страницу ввода логина и пароля.
  • Авторизация для фонового сервиса. Этот вариант подходит вам, если вы разрабатываете фоновый сервис без пользовательского интерфейса.

В результате прохождения любого из видов авторизации ваше приложение получит уникальный AccessToken(access_token), который вы должны использовать при вызове каждого метода Pyrus API. AccessToken(access_token) ограничен по времени и может быть отозван пользователем в любой момент. Тогда авторизацию необходимо будет пройти заново.

Регистрация приложения

После регистрации приложения вы получите Client ID и Client Secret. Эти идентификаторы необходимы для получения специального AccessToken(access_token), который требуется для безопасного вызова методов Pyrus API.

Вы должны войти в систему для регистрации OAuth.

Зарегистрировать нового клиента OAuth Зарегистрировать нового клиента OAuth Зарегистрировать нового клиента OAuth Зарегистрировать нового клиента OAuth Зарегистрировать нового клиента OAuth

Получение задачи

Чтение задачи реализовано с помощью метода веб сервиса GetTask. Метод GetTask принимает в качестве единственного параметра идентификатор задачи и возвращает объект, содержащий структуру TaskWithNotes.

В качестве REST точки используется адрес https://pyrus.com/restapi/v3/task/{taskid}, принимающий GET запрос, где {taskid} - идентификатор задачи.

Пример

GET https://pyrus.com/restapi/v3/task/1024
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело ответа

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481068800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Approvals": [[{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Person": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        }],
        [{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        }]],
        "Notes": [{
            "CreateDate": "/Date(1481068800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "ReassignedTo": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            },
            "AddedProjects": [{
                "Id": 1,"Name": "Root project"
            },
            {
                "Id": 3,
                "Name": "ChildProject",
                "Parent": {
                    "Id": 2,
                    "Name": "Another root project"
                }
            }],
            "DueDateChanged": "/Date(1481068800000)/",
            "ApprovalsAdded": [[{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }],
            [{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }]]
        }]
    }
}

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

403 Отсутствует доступ:

  • BehavioralTaskAccessViolation: Отсутствует доступ к задаче у пользователя, от имени которого совершена попытка изменить задачу, отсутствуют права на такое изменение;

Структура TaskWithNotes описывает задачу с комментариями и имеет следующие параметры:

    • Id: идентификатор задачи;
    • Text: текст задачи;
    • Responsible: пользователь, на которого назначена задача, является структурой Person;
    • DueDate: срок задачи, этот параметр является датой в UTC формате без часов, минут и секунд, если у задачи не установлен срок, параметр не заполняется;
    • Asap: флаг срочности задачи, если значение ложно, то параметр не заполняется;
    • Projects: массив проектов задачи;
    • CloseDate: дата закрытия задачи, если задача открыта, параметр не указывается;
    • CreateDate: дата создания задачи;
    • ModifiedDate: дата последнего изменения задачи;
    • ParentTaskId: идентификатор предшествующей задачи ;
    • Author: автор задачи, является структурой Person;
    • Approvals: согласования задачи, представляет собой массив шагов согласования, каждый из которых является массивом структур PersonApproval, описанных ниже. Некоторые этапы согласования могут быть пропущены, тогда массив структур PersonApproval будет равняется null;
    • Form: массив значений полей формы, может быть пустым;
    • Notes: массив комментариев, каждый элемент массива является структурой TaskNote, описанной ниже, у каждой задачи есть хотя бы один комментарий - начальный;
    • IsAnyRejected: флаг указывающий на то, что на одном или нескольких этапов утверждения было отклонение;

Структура TaskNote описывает комментарий задачи и имеет следующие параметры:

    • TaskId: ;
    • UserId: ;
    • CreateDate: дата создания комментария;
    • Author: автор комментария, является структурой Person;
    • Text: текст комментария, может быть пустым и не указываться;
    • ReassignedTo: на кого назначена задача, если в комментарии переназначения не было, параметр не указывается, является структурой Person;
    • ActivityAction: флаг закрытия или переоткрытия задачи, значение по умолчанию не указывается, является перечислением, принимающим следующие фиксированные значения: None - значение по умолчанию, оставить активность без изменений, Complete - закрыть задачу, MarkAsDuplicate - закрыть, как дубликат, MarkAsIrrelevant - закрыть, как неактуальную, Reopen - переоткрыть задачу;
    • ApprovalChoice: согласование автора комментария, если согласование не менялось, параметр не указывается, является перечислением, принимающим следующие фиксированные значения: Waiting - ожидается согласование, значение по умолчанию, Approved - утверждено, Rejected - отклонено, Revoked - перезапрошено;
    • AddedProjects: добавленные к задаче проекты, представляет собой массив проектов;
    • RemovedProjects: удаленные из задачи проекты, представляет собой массив проектов;
    • DueDateChanged: поменялся срок;
    • DueDateRemoved: флаг снятия срока, если флаг взведен, то DueDateChange не указывается;
    • ApprovalsAdded: добавленная маршрутизация, представляет собой массив шагов согласования, каждый из которых является массивом пользователей;
    • ApprovalsRemoved: удаляемая маршрутизация;
    • ApprovalsRerequested: перезапрашиваемая маршрутизация;
    • Attachments: присединенные файлы;
    • Id: id;
    • Form: массив значений полей формы, может быть пустым;

Структура PersonApproval описывает состояние согласования определенного пользователя и имеет следующие параметры:

    • Choice: согласование пользователя, значение по умолчанию может быть пропущено, является перечислением, принимающим следующие фиксированные значения: Waiting - ожидается согласование, значение по умолчанию, Approved - утверждено, Rejected - отклонено, Revoked - перезапрошено;

Структура Attachment описывает файл, приложенный к комментарию и имеет следующие параметры:

    • Id: Идентификатор;
    • Name: имя файла;
    • Size: размер файла в байтах;
    • DownloadUrl: Ссылка для загрузки;
    • ExistingId: Идентификатор первой версии файла;
    • MD5Hash: MD5 хеш;

Для задач-форм структура 'TaskWithNotes' содержит параметр 'Form'. Его значением будет массив объектов с типами-наследниками типа FormValue.

Структура FormValue описывает значение одного поля формы и имеет следующие параметры:

    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormField содержит вспомогательную информация о поле формы и имеет следующие параметры:

    • Id: идентификатор поля формы;
    • Type: идентификатор типа поля формы, является перечислением, принимающим следующие фиксированные значения: Unknown - неизвестный тип, Catalog - поле типа 'справочник', FileUrls - набор ссылок на файлы, Files - набор файлов, ApprovalStep - номер этапа согласования, на котором сейчас находится эта задача, Phone - поле типа 'телефон', Checkmark - поле типа 'галочка', Note - неизменяемое текстовое поле, Time - поле типа 'время', Assignee - ответственный за задачу, Author - автор задачи, ApprovalPerson - сотрудник, согласовавший эту задачу, ApprovalDate - дата согласования, ActivityStatus - статус задачи (закрыта/открыта), DueDate - срок, когда задача должна быть выполнена, CreationDate - дата создания формы, Title - заголовок группы полей, Date - поле типа 'дата', Person - поле типа 'пользователь', Project - поле типа 'проект', Decimal - поле типа 'деньги', Number - поле типа 'число', Flag - поле типа 'да/нет', Text - поле типа 'текст', Email - поле типа 'Email', ExternalFormAuthor - поле типа 'автор внешней формы';
    • Name: название поля поля формы;
    • ParentId: Id родительского поля;

Значение каждого поля формы передается в объекте с типом-наследником типа FormValue. Ниже перечислены все возможные типы-наследники.

Структура FormFieldActivityStatus.ValueType описывает значение статуса задачи (закрыта/открыта) и имеет следующие параметры:

    • ActivityStatus: статус задачи, является перечислением, принимающим следующие фиксированные значения: Opened - открыта, Closed - закрыта;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldApprovalDate.ValueType описывает поле 'дата согласования' и имеет следующие параметры:

    • ApprovalDate: дата согласования;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldApprovalPerson.ValueType предоставляет данные о сотруднике, согласовавший эту задачу и имеет следующие параметры:

    • ApprovalPerson: сотрудник, согласовавший эту задачу, является структурой Person;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldApprovalStep.ValueType предоставляет данные об этапе согласования, на котором сейчас находится эта задача, и имеет следующие параметры:

    • ApprovalStep: номер этапа согласования, на котором сейчас находится эта задача;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldAssignee.ValueType предоставляет данные об ответственном за задачу и имеет следующие параметры:

    • Assignee: ответственный за задачу, является структурой Person;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldAuthor.ValueType предоставляет данные об авторе задачи и имеет следующие параметры:

    • Author: автор задачи, является структурой Person;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldCheckmark.ValueType описывает значение поля типа 'галочка' и имеет следующие параметры:

    • Checkmark: значение поле типа 'галочка', является перечислением, принимающим следующие фиксированные значения: Checked, Unchecked;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldCreationDate.ValueType предоставляет дату создания формы и имеет следующие параметры:

    • CreationDate: дата создания формы;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldDate.ValueType описывает значение поля типа 'дата' и имеет следующие параметры:

    • Date: значение поля типа 'дата';
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldDecimal.ValueType описывает значение поля типа 'деньги' и имеет следующие параметры:

    • Decimal: значение поля типа 'деньги';
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldDueDate.ValueType предоставляет даные о сроке, когда задача должна быть выполнена, и имеет следующие параметры:

    • DueDate: срок, когда задача должна быть выполнена;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldFiles.ValueType представляет собой набор файлов и имеет следующие параметры:

    • Files: набор файлов;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldFlag.ValueType описывает значение поля типа 'да/нет' и имеет следующие параметры:

    • Flag: значение поля типа 'да/нет', является перечислением, принимающим следующие фиксированные значения: None, Checked, Unchecked;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldNote.ValueType предоставляет собой объект, возвращаемый для поля типа 'примечание', и имеет следующие параметры:

    • Tooltip: значение поля типа 'примечание';
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldNumber.ValueType описывает значение поля типа 'число' и имеет следующие параметры:

    • Number: значение поля типа 'число';
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldPerson.ValueType описывает значение поля типа 'пользователь' и имеет следующие параметры:

    • Person: значение поля типа 'пользователь', является структурой Person;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldPhone.ValueType описывает значение поля типа 'телефон' и имеет следующие параметры:

    • Phone: значение поля типа 'телефон' (объект с двумя полями: 'Prefix' и 'Number'), является структурой Phone;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldProject.ValueType описывает значение поля типа 'проект' и имеет следующие параметры:

    • Project: значение поля типа 'проект', является структурой Project;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldText.ValueType описывает значение поля типа 'текст' и имеет следующие параметры:

    • Text: значение поля типа 'текст';
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldTime.ValueType описывает значение поля типа 'время' и имеет следующие параметры:

    • Time: значение поля типа 'время' (объект с двумя целочисленными полями: 'UtcHour' и 'UtcMinute'), является структурой Time;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldTitle.ValueType предоставляет собой пустой объект, возвращаемый для заголовка группы полей, и имеет следующие параметры:

    • Rows: информация о текущих строках в табличном поле;
    • Checkmark: информация о значении отметки в необязательной группе;
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldCatalog.ValueType описывает значение поля типа 'справочник' и имеет следующие параметры:

    • CatalogItemId: ID значения поля типа 'справочник';
    • CatalogItemValues: значение поля типа 'справочник';
    • CatalogHeaders: заголовки для поля типа 'справочник';
    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Структура FormFieldUnknown.ValueType и имеет следующие параметры:

    • Field: вспомогательная информация о поле формы, является структурой FormField;
    • RowId: номер строки, если поле относится к таблице;

Внимание, передача некоторых типов полей формы через API поддерживается не полностью.

Методы

После прохождения авторизации Вы можете воспользоваться следующими методами системы:

  • Получение задачи
  • Получение списка задач
  • Получение всех задач
  • Создание задачи
  • Создание комментария
  • Получение профиля
  • Получение контактов

Все методы доступны только с использованием защищенного https канала и расположены на https://pyrus.com.

Система поддерживает REST.

Заголовок Content-Type

Pyrus API использует JSON в кач-ве формата данных, поэтому для каждого запроса необходимо записывать в заголовок Content-Type значение application/json.

Заголовок авторизации

Вместе с каждым запросом должен быть указан http заголовок Authorization, вычисляемый в соответствии с протоколом OAuth 2.0.

Сжатие данных

Все методы поддерживают стандартные алгоритмы gzip и deflate сжатия. Рекомендуется их использовать при работе с большими объемами данных.

Форматы данных

В интерфейсе используются следующие стандартные типы данных:

  • строковый
  • целочисленный
  • битовый флаг
  • датовый
  • массив
  • перечисления
  • структуры, объединяющие вышеперечисленные типы.

Датовый тип сериализуется в JSON формат как строка следующего вида: "/Date(1198908717056)/", где число в скобках является количеством миллисекунд, начиная с 1 января 1970 года в UTC формате. Для сериализации даты в xml используется ISO 8601 стандарт. Xml ответ от сервера всегда приходит с нулевой временной зоной, например: "2012-04-10T09:08:07Z". Миллисекунды в датах игнорируются.

Перечисления представляют собой строковый тип, принимающий один из нескольких фиксированных значений. Одно из фиксированных значений может являться значением по умолчанию и может быть не указано в теле запроса или в теле ответа.

Ниже описаны часто используемые структуры данных.

Структура Person описывает пользователя и имеет следующие параметры:

    • Id: идентификатор пользователя;
    • FirstName: имя, может быть пустым;
    • LastName: фамилия;
    • Email: электронный адрес пользователя;
    • CanSendNotification: можем ли слать сообщение;

Структура Project описывает проект и имеет следующие параметры:

    • Id: идентификатор проекта;
    • Name: имя проекта;
    • Parent: родительский проект, если проект - корневой, то родительский проект не указывается;

Обработка ошибок

В случае ошибочного вызова возвращается наиболее подходящий Status Code. Также, в случае ошибки предоставляется дополнительная информация, включающая строковые поля Code и Description. В случае REST запроса, будет возвращена json структура Error с указанными выше полями.

Ниже приведен пример ответа на неверный запрос.

REST

Заголовки ответа
Content-Encoding: gzip
Content-Type: application/json; charset=utf-8
Тело ответа
{ "ApiException" : { "Code" : "BadFormat", "Message" : "Some error text" } }

Строковый параметр ошибки Code содержит код ошибки. Коды сгруппированы по следующим признакам: BadFormat - ошибки форматирования, Authorization - ошибки авторизации, Behavioral - ошибки, связанные с правами доступа пользователя. Каждый метод может возвращать свои собственные ошибки, они описаны в секции метода. Ниже приведен список часто встречающихся типов ошибок:

400 Неверные параметры запроса:

  • BadFormat: Неверное значение в параметре вызываемого метода. Убедитесь, что все значения, передаваемые в кач-ве параметров вызываемого метода, имеют тип соответствующий типу параметра;
  • BadFormatInteger: Неверное значение в параметре числового типа. Убедитесь, что вы передаете правильное значение в параметре целочисленного типа;
  • BadFormatDate: Неверное значение в параметре типа дата. Убедитесь, что значение типа дата (например <b>DueDate</b> в методе <b>CreateTask</b>), передаваемое в кач-ве параметра запроса, имеет правильный формат;

401 Отсутствует авторизация:

  • AuthorizationError: Ошибка авторизации. Убедитесь, что вы прошли процесс авторизации;
  • AuthorizationErrorInvalidToken: Неверный токен авторизации. Получите новый токен выполнив соответствующую процедуру для веб-приложения или фонового сервиса заново;
  • AuthorizationErrorRevokedToken: Токен авторизации был отозван. Получите новый токен выполнив соответствующую процедуру для веб-приложения или фонового сервиса заново;
  • AuthorizationErrorExpiredToken: Время токена истекло. Получите новый токен выполнив соответствующую процедуру для веб-приложения или фонового сервиса заново;
  • AuthorizationErrorTokenNotSpecified: Токен авторизации не указан. Для вызова методов Pyrus API, необходимо указывать AccessToken(access_token) полученный в процессе авторизации;

403 Отсутствует доступ:

  • UnspecifiedAccessDenied: Нет доступа. Проверьте, что у пользователя, от имени которого совершается изменение задачи, есть права на это;

Получение списка задач

Есть две возможности получить список задач: получение задач из папки Входящие и поиск задач.

Получение списка задач из папки «Входящие»

Метод веб сервиса GetInbox принимает в качестве аргумента параметр MaximumItemsCount - максимальное количество задач, которое вернет сервер, если параметр не указан, сервер вернет не более 50 задач. Метод GetInbox возвращает структуру TaskList.

В качестве REST точки используется адрес https://pyrus.com/restapi/inbox принимающий GET запрос.

Пример

GET https://pyrus.com/restapi/inbox/3
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело ответа

{
    "Tasks": [{
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481155645997)/",
        "ModifiedDate": "/Date(1481155645997)/"
    },
    {
        "Id": 1025,
        "Text": "Another task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481155645998)/",
        "ModifiedDate": "/Date(1481155645998)/"
    },
    {
        "Id": 1026,
        "Text": "Closed task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1481155645000)/",
        "CreateDate": "/Date(1481155645998)/",
        "ModifiedDate": "/Date(1481155645998)/"
    }],
    "HasMoreTasks": true
}

Поиск задач

Метод веб сервиса SearchTasks принимает в качестве аргумента структуру SearchTasksParams - параметры поиска задач и возвращает структуру TaskList.

В качестве REST точки используется адрес https://pyrus.com/restapi/searchtasks принимающий POST запрос с аналогичной структурой параметров создаваемой задачи.

Пример

POST https://pyrus.com/restapi/searchtasks
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело запроса

{
    "AuthorId": 300,
    "MaximumItemsCount": 3
}

Тело ответа

{
    "Tasks": [{
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481155645998)/",
        "ModifiedDate": "/Date(1481155645998)/"
    },
    {
        "Id": 1025,
        "Text": "Another task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481155645998)/",
        "ModifiedDate": "/Date(1481155645998)/"
    },
    {
        "Id": 1026,
        "Text": "Closed task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1481155645000)/",
        "CreateDate": "/Date(1481155645998)/",
        "ModifiedDate": "/Date(1481155645998)/"
    }],
    "HasMoreTasks": true
}

Структура SearchTasksParams описывает параметры поиска задач и имеет следующие параметры:

    • ProjectIds: фильтр по проектам, представляет собой массив идентификаторов проектов;
    • IncludeClosedTasks: включать в поиск закрытые задачи, по умолчанию поиск осуществляется только по открытым задачам;
    • ParticipantIds: фильтр по участникам задачи, представляет собой массив идентификаторов пользователей;
    • AuthorId: идентификатор автора, по умолчанию не указывается;
    • ResponsibleId: идентификатор ответственного, по умолчанию не указывается;
    • MaximumItemsCount: максимальное количество задач, которое вернет сервер, если параметр не указан, сервер вернет не более 50 задач;
    • IncludeText: включая подстроки;
    • ExcludeText: исключая подстроки, если параметр указан, должен быть указан параметр IncludeText;
    • ActiveFrom: дата начала периода поиска задач;
    • ActiveTo: дата окончания периода поиска задач;

Структура TaskList представляет собой список задач и имеет следующие параметры:

    • Tasks: массив задач, каждый элемент массива является структурой Task;
    • HasMoreTasks: если флаг взведен, то сервер вернул первые N задач, для получения большего количества задач необходимо использовать параметр MaximumItemsCount, параметр HasMoreTasks не указывается, если сервер вернул все задачи по заданному критерию поиска;

Структура Task представляет собой задачу и имеет следующие параметры:

    • Id: идентификатор задачи;
    • Text: текст задачи;
    • Responsible: пользователь, на которого назначена задача, является структурой Person;
    • DueDate: срок задачи, этот параметр является датой в UTC формате без часов, минут и секунд, если у задачи не установлен срок, параметр не заполняется;
    • Asap: флаг срочности задачи, если значение ложно, то параметр не заполняется;
    • Projects: массив проектов задачи;
    • CloseDate: дата закрытия задачи, если задача открыта, параметр не указывается;
    • CreateDate: дата создания задачи;
    • ModifiedDate: дата последнего изменения задачи;
    • ParentTaskId: идентификатор предшествующей задачи ;

Получение всех задач

Получение всех задач, доступных пользователю.

Получение всех задач

Метод веб сервиса GetAllTasks принимает в качестве аргумента параметр MaximumItemsCount - максимальное количество задач, которое вернет сервер, если параметр не указан, сервер вернет не более 50 задач. Метод GetAllTasks структуру TaskList.

В качестве REST точки используется адрес https://pyrus.com/restapi/alltasks принимающий GET запрос.

Пример

GET https://pyrus.com/restapi/alltasks/3
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело ответа

{
    "Tasks": [{
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481155646000)/",
        "ModifiedDate": "/Date(1481155646000)/"
    },
    {
        "Id": 1025,
        "Text": "Another task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481155646000)/",
        "ModifiedDate": "/Date(1481155646000)/"
    },
    {
        "Id": 1026,
        "Text": "Closed task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1481155646000)/",
        "CreateDate": "/Date(1481155646000)/",
        "ModifiedDate": "/Date(1481155646000)/"
    }],
    "HasMoreTasks": true
}

Структура TaskList представляет собой список задач и имеет следующие параметры:

    • Tasks: массив задач, каждый элемент массива является структурой Task;
    • HasMoreTasks: если флаг взведен, то сервер вернул первые N задач, для получения большего количества задач необходимо использовать параметр MaximumItemsCount, параметр HasMoreTasks не указывается, если сервер вернул все задачи по заданному критерию поиска;

Структура Task представляет собой задачу и имеет следующие параметры:

    • Id: идентификатор задачи;
    • Text: текст задачи;
    • Responsible: пользователь, на которого назначена задача, является структурой Person;
    • DueDate: срок задачи, этот параметр является датой в UTC формате без часов, минут и секунд, если у задачи не установлен срок, параметр не заполняется;
    • Asap: флаг срочности задачи, если значение ложно, то параметр не заполняется;
    • Projects: массив проектов задачи;
    • CloseDate: дата закрытия задачи, если задача открыта, параметр не указывается;
    • CreateDate: дата создания задачи;
    • ModifiedDate: дата последнего изменения задачи;
    • ParentTaskId: идентификатор предшествующей задачи ;

Создание задачи

Метод веб сервиса AddTask принимает в качестве аргумента структуру AddTaskParams. Единственным обязательным параметром структуры является Text - текст создаваемой задачи. Метод AddTask возвращает объект, содержащий структуру TaskWithNotes.

В качестве REST точки используется адрес https://pyrus.com/restapi/addtask принимающий PUT запрос с аналогичной структурой параметров создаваемой задачи.

Пример

PUT https://pyrus.com/restapi/addtask
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело запроса

{
    "Text": "Hello world text",
    "ResponsibleId": 400,
    "AddedProjectIds": [1,3],
    "DueDate": "/Date(1481068800000)/"
}

Тело ответа

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1481068800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Approvals": [[{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Person": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        }],
        [{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        }]],
        "Notes": [{
            "CreateDate": "/Date(1481068800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "ReassignedTo": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            },
            "AddedProjects": [{
                "Id": 1,"Name": "Root project"
            },
            {
                "Id": 3,
                "Name": "ChildProject",
                "Parent": {
                    "Id": 2,
                    "Name": "Another root project"
                }
            }],
            "DueDateChanged": "/Date(1481068800000)/",
            "ApprovalsAdded": [[{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }],
            [{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }]]
        }]
    }
}

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

400 Неверные параметры запроса:

  • BehavioralEmptyText: Текст новой задачи должен быть заполнен;
  • BehavioralUnrecognizedAttachmentId: Идентификатор прикладываемого файла неверен. У пользователя отсутствует файл с указаным идентификатором;

403 Отсутствует доступ:

  • BehavioralPersonAccessViolation: Отсутствует доступ к пользователю; помимо указанного кода, структура ошибки будет содержать параметр PersonId. Проверьте, что пользователь является супрвайзером и его организация совпадает с организацией, в которой создан справочник;
  • BehavioralProjectAccessViolation: Отсутствует доступ к проекту; помимо указанного кода, структура ошибки будет содержать параметр ProjectId. Убедитесь, что указанный проект существует и он не закрыт;

Структура AddTaskParams описывает параметры создаваемой задачи и имеет следующие параметры:

    • Text: текст задачи, должен быть непустой.;
    • ResponsibleId: идентификатор пользователя, на которого будет поставлена задача. Если параметр не заполнен задача будет назначена автору;
    • AddedProjectIds: массив идентификаторов проектов создаваемой задачи;
    • DueDate: срок задачи, является датой в UTC формате без часов, минут и секунд;
    • AddedApprovals: представляет собой маршрутизацию, является массивом шагов согласования, состоящим из массивов идентификаторов пользователей;
    • AttachmentIds: массив уникальных идентификаторов загруженных файлов, как получить идентификатор читайте здесь;
    • AttachmentUrls: массив ссылок на файлы для загрузки в задачу (вида:{"Url":"url","Name":"name"});
    • Subject: новый заголовок задачи;
    • ParentTaskId: надзадача (доступно для заполнения только при создании задачи);

Важно

Если не указан параметр ResponsibleId, задача будет назначена автору.

Важно

В случае, когда к задаче добавляются проекты с заданной маршрутизацией по умолчанию, сервер автоматически добавляет ее к задаче в дополнение к указанной маршрутизации в запросе.

Создание формы

Задача по форме может быть создана с помощью AddForm метода. AddForm принимает на вход структуру AddFormParams в качестве аргумента. Метод AddForm возвращает созданную задачу в виде объекта, содержащего структуру TaskWithNotes.

В качестве REST точки используется адрес https://pyrus.com/restapi/addform принимающий PUT запрос.

Пример

PUT https://pyrus.com/restapi/addform
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело запроса

{
    "TemplateId": 1000,
    "Values": [{
        "FieldId": 1,"Text": "Hello world"
    },
    {
        "FieldId": 2,
        "Date": "/Date(1481155200000)/"
    },
    {
        "FieldId": 3,
        "Number": 10.0
    },
    {
        "FieldId": 4,
        "Amount": 100.21
    },
    {
        "FieldId": 5,
        "ProjectId": 1001
    },
    {
        "FieldId": 6,
        "PersonId": 300
    },
    {
        "FieldId": 7,
        "AssigneeId": 400
    },
    {
        "FieldId": 8,
        "Checkmark": "Checked"
    },
    {
        "FieldId": 9,
        "Flag": "Checked"
    },
    {
        "FieldId": 10,
        "DueDate": "/Date(1482019200000)/"
    },
    {
        "FieldId": 11,"Time": {
            "UtcHour": 10,
            "UtcMinute": 53
        }
    },
    {
        "FieldId": 12,
        "Phone": {
            "Prefix": null,
            "Number": "987654321"
        }
    }]
}

Тело ответа

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Form:  Hello world",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1482019200000)/",
        "Projects": [{
            "Id": 1000,
            "Name": "Form"
        },
        {
            "Id": 1003,
            "Name": "List item",
            "Parent": {
                "Id": 1002,
                "Name": "List",
                "Parent": {
                    "Id": 1000,
                    "Name": "Form"
                }
            }
        }],
        "CreateDate": "/Date(1481068800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Form": [{
            "Field": {
                "Id": 1,"Type": "Text",
                "Name": "Text field"
            },
            "Text": "Hello world"
        },
        {
            "Field": {
                "Id": 2,
                "Type": "Date",
                "Name": "Date field"
            },
            "Date": "/Date(1481155200000)/"
        },
        {
            "Field": {
                "Id": 3,
                "Type": "Number",
                "Name": "Number field"
            },
            "Number": 10
        },
        {
            "Field": {
                "Id": 4,
                "Type": "Decimal",
                "Name": "Money field"
            },
            "Decimal": 100.21
        },
        {
            "Field": {
                "Id": 5,
                "Type": "Project",
                "Name": "List field"
            },
            "Project": {
                "Id": 1003,
                "Name": "List item",
                "Parent": {
                    "Id": 1002,
                    "Name": "List",
                    "Parent": {
                        "Id": 1000,
                        "Name": "Form"
                    }
                }
            }
        },
        {
            "Field": {
                "Id": 6,
                "Type": "Person",
                "Name": "Contact field"
            },
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Field": {
                "Id": 7,
                "Type": "Assignee",
                "Name": "Assignee field"
            },
            "Assignee": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        },
        {
            "Field": {
                "Id": 8,
                "Type": "Checkmark",
                "Name": "Checkmark field"
            },
            "Checkmark": "Checked"
        },
        {
            "Field": {
                "Id": 9,
                "Type": "Flag",
                "Name": "Flag field"
            },
            "Flag": "Checked"
        },
        {
            "Field": {
                "Id": 10,
                "Type": "DueDate",
                "Name": "Due date field"
            },
            "DueDate": "/Date(1482019200000)/"
        },
        {
            "Field": {
                "Id": 11,"Type": "Time",
                "Name": "Time field"
            },
            "Time": {
                "UtcHour": 10,
                "UtcMinute": 53
            }
        },
        {
            "Field": {
                "Id": 12,
                "Type": "Phone",
                "Name": "Phone field"
            },
            "Phone": {
                "Prefix": "+123",
                "Number": "987654321"
            }
        }]
    }
}

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

400 Неверные параметры запроса:

  • BehavioralUnrecognizedAttachmentId: Идентификатор прикладываемого файла неверен. У пользователя отсутствует файл с указаным идентификатором;
  • BehavioralIrrelevantTemplateFieldIdSpecified: Идентификатор поля формы некорректен: либо поле формы отсутствует, либо оно было удалено;

403 Отсутствует доступ:

  • BehavioralPersonAccessViolation: Отсутствует доступ к пользователю; помимо указанного кода, структура ошибки будет содержать параметр PersonId. Проверьте, что пользователь является супрвайзером и его организация совпадает с организацией, в которой создан справочник;
  • BehavioralProjectAccessViolation: Отсутствует доступ к проекту; помимо указанного кода, структура ошибки будет содержать параметр ProjectId. Убедитесь, что указанный проект существует и он не закрыт;
  • BehavioralTemplateAccessViolation: Отсутствует доступ к шаблону; помимо указанного кода, структура ошибки будет содержать параметр TemplateId. Убедитесь, что шаблон существует и у пользователя есть доступ к проекту, который ассоциирован с этим шаблоном;

Структура TaskWithNotes описывает задачу с комментариями и имеет следующие параметры:

    • Id: идентификатор задачи;
    • Text: текст задачи;
    • Responsible: пользователь, на которого назначена задача, является структурой Person;
    • DueDate: срок задачи, этот параметр является датой в UTC формате без часов, минут и секунд, если у задачи не установлен срок, параметр не заполняется;
    • Asap: флаг срочности задачи, если значение ложно, то параметр не заполняется;
    • Projects: массив проектов задачи;
    • CloseDate: дата закрытия задачи, если задача открыта, параметр не указывается;
    • CreateDate: дата создания задачи;
    • ModifiedDate: дата последнего изменения задачи;
    • ParentTaskId: идентификатор предшествующей задачи ;
    • Author: автор задачи, является структурой Person;
    • Approvals: согласования задачи, представляет собой массив шагов согласования, каждый из которых является массивом структур PersonApproval, описанных ниже. Некоторые этапы согласования могут быть пропущены, тогда массив структур PersonApproval будет равняется null;
    • Form: массив значений полей формы, может быть пустым;
    • Notes: массив комментариев, каждый элемент массива является структурой TaskNote, описанной ниже, у каждой задачи есть хотя бы один комментарий - начальный;
    • IsAnyRejected: флаг указывающий на то, что на одном или нескольких этапов утверждения было отклонение;

Структура AddFormParams описывает создаваемую форму и имеет следующие параметры:

    • TemplateId: идентификатор шаблона, это поле обязательно для заполнения;
    • Values: массив значений создаваемой формы, каждый элемент массива является структурой NewFormValue;
    • AttachmentIds: массив уникальных идентификаторов загруженных файлов, как получить идентификатор читайте здесь;
    • AttachmentUrls: массив ссылок на файлы для загрузки в задачу;
    • ResponsibleId: идентификатор пользователя, на которого будет поставлена задача. Если параметр не заполнен задача будет назначена автору;
    • ParentTaskId: надзадача;

Структура NewFormValue описывает новое значение поля формы, каждое значение включает в себя обязательное поле FieldId и одно из дополнительных, в зависимости от типа поля формы и имеет следующие параметры:

    • FieldId: идентификатор поля формы, является обязательным;
    • Text: значение текстового поля;
    • Number: значение поля типа число;
    • ProjectId: значение поля типа список (Больше не поддерживается. Начиная со 2-й версии следует использовать ProjectIds);
    • ProjectIds: значение мультивыборного поля типа список (версия 2);
    • Date: значение датового поля;
    • Amount: значение поля типа деньги;
    • PersonId: значение поля типа контакт, является идентификатором пользователя;
    • AssigneeId: значение поля типа ответственный, является идентификатором пользователя;
    • Checkmark: знчачение поля типа да\нет, является перечислением, принимающим следующие фиксированные значения: Checked, Unchecked;
    • Flag: значение поля типа галочка, является перечислением, принимающим следующие фиксированные значения: None, Checked, Unchecked;
    • DueDate: значение поля типа срок задачи;
    • Time: значение поля типа срок, является структурой Time;
    • Phone: значение поля типа телефон, используется только параметр Number, является структурой Phone;
    • Files: массив уникальных идентификаторов загруженных файлов, как получить идентификатор читайте здесь;
    • FileUrls: массив ссылок на файлы для добавления к задаче (вида: {"Url":"url","Name":"name"});
    • Email: значение поля типа эл. почта;
    • RowId: номер текущей строки (версия 2);
    • Rows: строки таблицы (версия 2);
    • CatalogItem: ID выбранного элемента типа справочник;
    • CurrentStep: ;

Важно

Если какое-либо значение поля не указано в запросе, сервер автоматически подставит в форму значение поле по-умолчанию.

Важно

В случае, когда к форме добавляются значения полей типа список с заданными согласованиями, сервер автоматически добавляет их к форме.

Важно

Ответственный за задачу вычисляется следующим образом: значение поля формы типа Ответственный, если оно указано, иначе ответственный по-умолчанию в проекте соответствующего поля формы типа Список, иначе автор задачи.

Важно

Срок задачи берется из поля типа Срок задачи, если оно задано.

Обработка ошибок

Вызов методов Pyrus API может вернуть следующие коды ошибок:

400 Неверные параметры запроса:

  • BadFormatInteger: Неверное значение в параметре числового типа. Убедитесь, что вы передаете правильное значение в параметре целочисленного типа;
  • BehavioralEmptyText: Текст новой задачи должен быть заполнен;
  • BadFormatDate: Неверное значение в параметре типа дата. Убедитесь, что значение типа дата (например <b>DueDate</b> в методе <b>CreateTask</b>), передаваемое в кач-ве параметра запроса, имеет правильный формат;
  • BehavioralUnrecognizedAttachmentId: Идентификатор прикладываемого файла неверен. У пользователя отсутствует файл с указаным идентификатором;
  • BadFormat: Неверное значение в параметре вызываемого метода. Убедитесь, что все значения, передаваемые в кач-ве параметров вызываемого метода, имеют тип соответствующий типу параметра;
  • BehavioralIrrelevantTemplateFieldIdSpecified: Идентификатор поля формы некорректен: либо поле формы отсутствует, либо оно было удалено;

401 Отсутствует авторизация:

  • AuthorizationErrorInvalidLoginOrSecurityKey: Неверный логин или секретный ключ. Убедитесь, что вы использовали верный логин и секретный ключ для получения AccessToken(access_token) фонового сервиса;
  • AuthorizationErrorInvalidClientId: Неверный Client ID. Убедитесь, что вы используете Client ID полученный при регистрации приложения;
  • AuthorizationErrorExpiredToken: Время токена истекло. Получите новый токен выполнив соответствующую процедуру для веб-приложения или фонового сервиса заново;
  • AuthorizationErrorRevokedToken: Токен авторизации был отозван. Получите новый токен выполнив соответствующую процедуру для веб-приложения или фонового сервиса заново;
  • AuthorizationErrorInvalidToken: Неверный токен авторизации. Получите новый токен выполнив соответствующую процедуру для веб-приложения или фонового сервиса заново;
  • AuthorizationError: Ошибка авторизации. Убедитесь, что вы прошли процесс авторизации;
  • AuthorizationErrorTokenNotSpecified: Токен авторизации не указан. Для вызова методов Pyrus API, необходимо указывать AccessToken(access_token) полученный в процессе авторизации;

403 Отсутствует доступ:

  • BehavioralTaskAccessViolation: Отсутствует доступ к задаче у пользователя, от имени которого совершена попытка изменить задачу, отсутствуют права на такое изменение;
  • BehavioralPersonAccessViolation: Отсутствует доступ к пользователю; помимо указанного кода, структура ошибки будет содержать параметр PersonId. Проверьте, что пользователь является супрвайзером и его организация совпадает с организацией, в которой создан справочник;
  • BehavioralProjectAccessViolation: Отсутствует доступ к проекту; помимо указанного кода, структура ошибки будет содержать параметр ProjectId. Убедитесь, что указанный проект существует и он не закрыт;
  • BehavioralTemplateAccessViolation: Отсутствует доступ к шаблону; помимо указанного кода, структура ошибки будет содержать параметр TemplateId. Убедитесь, что шаблон существует и у пользователя есть доступ к проекту, который ассоциирован с этим шаблоном;
  • BehavioralMaxContentLengthExceeded: Превышен лимит объема загружаемого файла. Для не-премиум аккаунтов, объем загружаемого файла не должен превышать 5Mb;
  • UnspecifiedAccessDenied: Нет доступа. Проверьте, что у пользователя, от имени которого совершается изменение задачи, есть права на это;

Создание комментария

Метод веб сервиса AddComment принимает в качестве аргумента структуру AddCommentParams. Метод AddComment возвращает измененную задачу в виде объекта, содержащего структуру TaskWithNotes.

В качестве REST точки используется адрес https://pyrus.com/restapi/addcomment принимающий PUT запрос с аналогичной структурой параметров создаваемого комментария.

Следующий пример закрывает задачу

Пример

PUT https://pyrus.com/restapi/addcomment
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело запроса

{
    "TaskId": 1024,
    "Text": "Closing as irrelevant",
    "ActivityAction": "MarkAsIrrelevant"
}

Тело ответа

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1481068800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1481068800000)/",
        "CreateDate": "/Date(1481068800000)/",
        "ModifiedDate": "/Date(1481068800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Approvals": [[{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Person": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        }],
        [{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        }]],
        "Notes": [{
            "CreateDate": "/Date(1481068800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "ReassignedTo": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            },
            "AddedProjects": [{
                "Id": 1,"Name": "Root project"
            },
            {
                "Id": 3,
                "Name": "ChildProject",
                "Parent": {
                    "Id": 2,
                    "Name": "Another root project"
                }
            }],
            "DueDateChanged": "/Date(1481068800000)/",
            "ApprovalsAdded": [[{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }],
            [{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }]]
        },
        {
            "CreateDate": "/Date(1481068800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "Text": "Closing as irrelevant",
            "ActivityAction": "MarkAsIrrelevant"
        }]
    }
}

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

400 Неверные параметры запроса:

  • BehavioralUnrecognizedAttachmentId: Идентификатор прикладываемого файла неверен. У пользователя отсутствует файл с указаным идентификатором;

403 Отсутствует доступ:

  • UnspecifiedAccessDenied: Нет доступа. Проверьте, что у пользователя, от имени которого совершается изменение задачи, есть права на это;
  • BehavioralTaskAccessViolation: Отсутствует доступ к задаче у пользователя, от имени которого совершена попытка изменить задачу, отсутствуют права на такое изменение;
  • BehavioralPersonAccessViolation: Отсутствует доступ к пользователю; помимо указанного кода, структура ошибки будет содержать параметр PersonId. Проверьте, что пользователь является супрвайзером и его организация совпадает с организацией, в которой создан справочник;

Структура AddCommentParams описывает создаваемый комментарий и имеет следующие параметры:

    • TaskId: идентификатор задачи. Параметр TaskId является обязательным;
    • Text: текст комментария, может быть пустым;
    • ResponsibleId: идентификатор пользователя, на которого будет поставлена задача, Если параметр не заполнен задача не будет переназначена;
    • AddedProjectIds: массив идентификаторов добавляемых к задаче проектов;
    • DueDate: срок задачи, является датой в UTC формате без часов, минут и секунд;
    • AddedApprovals: добавляемая маршрутизация, является массивом шагов согласования, состоящим из массивов идентификаторов пользователей;
    • ActivityAction: флаг закрытия или переоткрытия задачи, значение по умолчанию: None - не менять статус активности задачи, является перечислением, принимающим следующие фиксированные значения: None - значение по умолчанию, оставить активность без изменений, Complete - закрыть задачу, MarkAsDuplicate - закрыть, как дубликат, MarkAsIrrelevant - закрыть, как неактуальную, Reopen - переоткрыть задачу;
    • ApprovalChoice: согласование комментирующего, является перечислением, принимающим следующие фиксированные значения: Waiting - ожидается согласование, значение по умолчанию, Approved - утверждено, Rejected - отклонено, Revoked - перезапрошено;
    • RemovedProjectIds: удаляемые проекты, представляет собой массив идентификаторов проектов;
    • ClearDueDate: флаг снятия срока задачи, если флаг взведен, срок снимается;
    • RemovedApprovals: удаляемая маршрутизация;
    • RerequestedApprovals: перезапрашиваемая маршрутизация;
    • AttachmentIds: массив уникальных идентификаторов загруженных файлов, как получить идентификатор читайте здесь;
    • FormChanges: массив элементов с типом NewFormValue, обновляемые значения формы, подробнее о структуре NewFormValue читайте здесь;
    • ApprovalStage: этап согласования;
    • AttachmentUrls: массив ссылок на файлы для загрузки в задачу (вида:{"Url":"url","Name":"name"});
    • Subject: новый заголовок задачи;
    • ParentTaskId: надзадача (доступно для заполнения только при создании задачи);

Все параметры структуры, кроме TaskId не являются обязательными для заполнения, при этом, если метод не изменит указанную задачу и не имеет заполненного текста, комментарий добавлен не будет.

Используя параметр FormChanges, вы можете изменить значения формы в задаче. Если вы не хотите менять значение какого-либо поля, просто не включайте его в список изменяемых значений FormChanges.

Важно

Вы не можете менять значения полей формы следующих типов: Срок задачи и Ответственный. Воспользуйтесь соответствующими полями DueDate и AssigneeId структуры AddCommentParams.

Получение профиля

Для получения информации о пользователе, который выдал права доступа к системе, используется метод веб сервиса GetProfile. Метод GetProfile возвращает объект, содержащий структуру Profile.

В качестве REST точки используется адрес https://pyrus.com/restapi/profile, принимающий GET запрос.

Пример

GET https://pyrus.com/restapi/profile
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело ответа

{
    "Profile": {
        "Id": 400,
        "FirstName": "Bill",
        "LastName": "Smith",
        "Email": "bill.smith@somedomain.edu",
        "Locale": "ru-RU",
        "CanMakeBackup": false,
        "CanSendLogs": false,
        "CanSyncCatalogs": false
    }
}

Структура Profile описывает профиль пользователя и имеет следующие параметры:

    • Id: идентификатор пользователя;
    • FirstName: имя, может быть пустым;
    • LastName: фамилия;
    • Email: электронный адрес пользователя;
    • Locale: текущая локаль пользователя, является перечислением, принимающим следующие фиксированные значения: ru-RU, en-US, en-GB;
    • CanSendNotification: можем ли слать сообщение;
    • CanMakeBackup: может ли создавать бекап;
    • CanSendLogs: может ли отправлять логи;
    • Roles: список ролей пользователя;
    • CanSyncCatalogs: может ли синхронизировать справочники;

Получение контактов

Для получения списка доступных контактов, используется метод веб сервиса GetContacts. Метод GetContacts возвращает объект, содержащий массив структур Organization.

В качестве REST точки используется адрес https://pyrus.com/restapi/contacts, принимающий GET запрос.

Пример

GET https://pyrus.com/restapi/contacts
Header Authorization: Bearer gAAAAA15vmSeoj*******

Тело ответа

{
    "Organizations": [{
        "Id": 10,
        "Name": "Bill's Ltd.",
        "Persons": [{
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        }]
    }]
}

Структура Organization описывает организацию и имеет следующие параметры:

    • Id: идентификатор организации;
    • Name: название организации;
    • Persons: список пользователей;

Структура Person описывает пользователя и имеет следующие параметры:

    • Id: идентификатор пользователя;
    • FirstName: имя, может быть пустым;
    • LastName: фамилия;
    • Email: электронный адрес пользователя;
    • CanSendNotification: можем ли слать сообщение;

Загрузка файла

Pyrus API позволяет прикладывать файлы к задачам. Для этого необходимо выполнить следующие шаги:

  • Загрузите отдельный файл на сервер Pyrus и получите его строковый уникальный идентификатор.
  • Укажите уникальный идентификатор в параметре AttachmentIds следующих структурах соответственно: AddTaskParams или AddCommentParams.

Для загрузки файла на сервер используйте POST запрос по адресу https://pyrus.com/restapi/upload. В ответе будет содержаться структура UploadedFile с единственным строковым параметром UploadedFileId - уникальным идентификатором загруженного файла. Не забудьте использовать HTTP Header Authorization аналогично остальным запросам.

Заголовок Content-Type

Для загрузки файла необходимо выставлять заголовку Content-Type значение multipart/form-data; boundary=8d2f42366b41441 где boundary это некоторый идентификатор, которым будет начинаться и заканчиваться тело файла в запросе. Кроме того нужно указывать заголовок Content-Length c учетом длины boundary.

Пример

POST https://pyrus.com/restapi/upload
Authorization: Bearer gAAA*****
Content-Type: multipart/form-data; boundary=8d2f42366b41441
Host: pyrus.com
Content-Length: 5222
--8d2f42366b41441
Content-Disposition: form-data; name="file"; filename="filename.jpg"
Content-Type: application/octet-stream
// здесь должно быть тело файла
--8d2f42366b41441--

Один файл на запрос

Загружайте ровно один файл, используя указанный запрос. Если необходимо загрузить несколько файлов, запустите запрос несколько раз соответственно.

Уникальный идентификатор

Не используйте уникальный идентификатор более одного раза. Вторая попытка повлечет ошибку.

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

403 Отсутствует доступ:

  • BehavioralMaxContentLengthExceeded: Превышен лимит объема загружаемого файла. Для не-премиум аккаунтов, объем загружаемого файла не должен превышать 5Mb;

Авторизация для веб-приложения

Чтобы пользователь вашего веб-сервиса мог работать с Pyrus, вы должны реализовать стандартный протокол авторизации клиента OAuth 2.0. Этот метод является самым безопасным. При такой авторизации ваше приложение не запрашивает пароль пользователя, а пользователь сообщает свой пароль по зашифрованному каналу напрямую сервису Pyrus.

Для реализации следует сделать следующие шаги:

  • 1. Зарегистрировать приложение, после регистрации вы получите уникальный идентификатор вашего приложения Client ID.

  • 2. Написать код, который в нужный момент направит пользователя на адрес https://pyrus.com/oauth (указав Client ID). На этой странице пользователь увидит форму ввода логина и пароля Pyrus. После успешного прохождения авторизации, пользователь может быть перенаправлен в ваше веб-приложение, которое получит уникальный разовый code.

  • 3. Сделать вызов к Pyrus, который обменяет разовый code на постоянный access_token.

  • Теперь вы можете использовать access_token во всех вызовах API. Когда токен устареет или пользователь отзовет свое разрешение, в ответ на очередной запрос вы получите ошибку с HTTP-кодом 401 Bad Authorization. Тогда нужно будет предложить пользователю пройти авторизацию заново (шаг 2).

Как получить access_token?

Чтобы получить access_token и вызвать метод API от имени пользователя Pyrus, нужно выполнить несколько простых шагов:

1. Направить веб-браузер пользователя на https://pyrus.com/oauth. Запрос должен содержать параметр redirect_uri с адресом, на который должен быть доставлен код авторизации или сообщения об ошибках. Если пользователь еще не вошел в Pyrus, ему предложат ввести логин и пароль. Кроме того он должен будет подтвердить, что предоставляет вашему приложению доступ к своим данным в Pyrus.

2. Далее наш сервер перенаправит пользователя на выбранный им Url. В случае успеха параметр code будет содержать код авторизации. Если произошла ошибка или пользователь отказался предоставить доступ, то описание ошибки можно найти в параметре error.

Если ваше приложение запускается на локальном компьютере пользователя (не в веб-браузере), укажите параметр redirect_uri равным nowebserver. В этом случае вместо перенаправления веб-браузера на redirect_uri, сервер запишет параметр code в заголовок (тег title) и в содержимое (тег body) страницы ответа.

3. Сформировать POST-запрос на https://pyrus.com/oauthtoken, в ответе будет access_token. В запрос также нужно включить:

  • client_id: ваш Client ID
  • client_secret: ваш Client Secret
  • grant_type: authorization_code на данный момент это единственное поддерживаемое значение
  • redirect_uri: значение redirect_uri, которое использовалось на шаге 1
  • code: код полученный на шаге 2

Пример

1. Запрашиваем code:

https://pyrus.com/oauth?client_id=CLIENT_ID&redirect_uri=REDIRECT-URI&response_type=code

REDIRECT-URI должен быть в URL-кодировке.

2. Получаем ответ:

http://your-redirect-uri?code=CODE

3. Запрашиваем access_token:

curl \
        -F 'client_id=CLIENT-ID' \
        -F 'client_secret=CLIENT-SECRET' \
        -F 'grant_type=authorization_code' \
        -F 'redirect_uri=YOUR-REDIRECT-URI' \
        -F 'code=CODE' \
        https://pyrus.com/oauthtoken

4. Получаем ответ:

{
    "access_token": "fb2e77d.47a0479900504cb3ab4a1f626d174d2d"
}

Авторизация для фонового сервиса

Для авторизации вам нужно сделать следующие шаги:

  • 1. Зарегистрировать приложение, после регистрации вы получите уникальный идентификатор вашего приложения Client ID.

  • 2. Получить секретный ключ в меню Настройки → Авторизация приложений . Если у вас еще нет секретного ключа, то нажмите на кнопку Получить новый ключ. Секретный ключ позволяет обеспечить безопасную работу с сервисами, которые не обладают пользовательским интерфейсом и не имеют возможности передавать логин и пароль через специальную форму.

  • 3. Получить AccessToken.

  • Теперь вы можете использовать AccessToken во всех вызовах API.

  • После получения нового секретного ключа, действующий AccessToken станет невалидным.

Как получить AccessToken?

Для этого нужно вызвать метод GetAccessToken, передав на сервер следующие параметры: логин, секретный ключ и Client ID приложения.

В качестве REST точки используется адрес https://pyrus.com/restapi/getaccesstoken принимающий POST запрос.

Пример

POST https://pyrus.com/restapi/getaccesstoken

Тело запроса

{
    "Login": "bill.smith@somedomain.edu",
    "SecurityKey": "******",
    "ClientId": "1234abcd-1234-abcd-1234-abcd1234abcd"
}

Тело ответа

{
    "AccessToken": "gAAAAA15vmSeoj*******"
}

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

401 Отсутствует авторизация:

  • AuthorizationErrorInvalidLoginOrSecurityKey: Неверный логин или секретный ключ. Убедитесь, что вы использовали верный логин и секретный ключ для получения AccessToken(access_token) фонового сервиса;
  • AuthorizationErrorInvalidClientId: Неверный Client ID. Убедитесь, что вы используете Client ID полученный при регистрации приложения;

Структура GetTokenParams описывает параметры запроса получения токена доступа и имеет следующие параметры:

    • Login: логин пользователя;
    • SecurityKey: секретный ключ пользователя;
    • ClientId: идентификатор приложения (сlient_id);

Авторизация для фонового сервиса

Для авторизации вам нужно сделать следующие шаги:

  • 1. Зарегистрировать приложение, после регистрации вы получите уникальный идентификатор вашего приложения Client ID.

  • 2. Получить секретный ключ в меню Настройки → Авторизация приложений . Если у вас еще нет секретного ключа, то нажмите на кнопку Получить новый ключ. Секретный ключ позволяет обеспечить безопасную работу с сервисами, которые не обладают пользовательским интерфейсом и не имеют возможности передавать логин и пароль через специальную форму.

  • 3. Получить AccessToken.

  • Теперь вы можете использовать AccessToken во всех вызовах API.

  • После получения нового секретного ключа, действующий AccessToken станет невалидным.

Как получить AccessToken?

Для этого нужно вызвать метод GetAccessToken, передав на сервер следующие параметры: логин, секретный ключ и Client ID приложения.

В качестве REST точки используется адрес https://pyrus.com/restapi/getaccesstoken принимающий POST запрос.

Пример

POST https://pyrus.com/restapi/getaccesstoken

Тело запроса

{
    "Login": "bill.smith@somedomain.edu",
    "SecurityKey": "******",
    "ClientId": "1234abcd-1234-abcd-1234-abcd1234abcd"
}

Тело ответа

{
    "AccessToken": "gAAAAA15vmSeoj*******"
}

Помимо ошибок авторизации и форматирования, данный метод может вернуть следующие коды ошибок:

401 Отсутствует авторизация:

  • AuthorizationErrorInvalidLoginOrSecurityKey: Неверный логин или секретный ключ. Убедитесь, что вы использовали верный логин и секретный ключ для получения AccessToken(access_token) фонового сервиса;
  • AuthorizationErrorInvalidClientId: Неверный Client ID. Убедитесь, что вы используете Client ID полученный при регистрации приложения;

Структура GetTokenParams описывает параметры запроса получения токена доступа и имеет следующие параметры:

    • Login: логин пользователя;
    • SecurityKey: секретный ключ пользователя;
    • ClientId: идентификатор приложения (сlient_id);

Авторизация для веб-приложения

Чтобы пользователь вашего веб-сервиса мог работать с Pyrus, вы должны реализовать стандартный протокол авторизации клиента OAuth 2.0. Этот метод является самым безопасным. При такой авторизации ваше приложение не запрашивает пароль пользователя, а пользователь сообщает свой пароль по зашифрованному каналу напрямую сервису Pyrus.

Для реализации следует сделать следующие шаги:

  • 1. Зарегистрировать приложение, после регистрации вы получите уникальный идентификатор вашего приложения Client ID.

  • 2. Написать код, который в нужный момент направит пользователя на адрес https://pyrus.com/oauth (указав Client ID). На этой странице пользователь увидит форму ввода логина и пароля Pyrus. После успешного прохождения авторизации, пользователь может быть перенаправлен в ваше веб-приложение, которое получит уникальный разовый code.

  • 3. Сделать вызов к Pyrus, который обменяет разовый code на постоянный access_token.

  • Теперь вы можете использовать access_token во всех вызовах API. Когда токен устареет или пользователь отзовет свое разрешение, в ответ на очередной запрос вы получите ошибку с HTTP-кодом 401 Bad Authorization. Тогда нужно будет предложить пользователю пройти авторизацию заново (шаг 2).

Как получить access_token?

Чтобы получить access_token и вызвать метод API от имени пользователя Pyrus, нужно выполнить несколько простых шагов:

1. Направить веб-браузер пользователя на https://pyrus.com/oauth. Запрос должен содержать параметр redirect_uri с адресом, на который должен быть доставлен код авторизации или сообщения об ошибках. Если пользователь еще не вошел в Pyrus, ему предложат ввести логин и пароль. Кроме того он должен будет подтвердить, что предоставляет вашему приложению доступ к своим данным в Pyrus.

2. Далее наш сервер перенаправит пользователя на выбранный им Url. В случае успеха параметр code будет содержать код авторизации. Если произошла ошибка или пользователь отказался предоставить доступ, то описание ошибки можно найти в параметре error.

Если ваше приложение запускается на локальном компьютере пользователя (не в веб-браузере), укажите параметр redirect_uri равным nowebserver. В этом случае вместо перенаправления веб-браузера на redirect_uri, сервер запишет параметр code в заголовок (тег title) и в содержимое (тег body) страницы ответа.

3. Сформировать POST-запрос на https://pyrus.com/oauthtoken, в ответе будет access_token. В запрос также нужно включить:

  • client_id: ваш Client ID
  • client_secret: ваш Client Secret
  • grant_type: authorization_code на данный момент это единственное поддерживаемое значение
  • redirect_uri: значение redirect_uri, которое использовалось на шаге 1
  • code: код полученный на шаге 2

Пример

1. Запрашиваем code:

https://pyrus.com/oauth?client_id=CLIENT_ID&redirect_uri=REDIRECT-URI&response_type=code

REDIRECT-URI должен быть в URL-кодировке.

2. Получаем ответ:

http://your-redirect-uri?code=CODE

3. Запрашиваем access_token:

curl \
        -F 'client_id=CLIENT-ID' \
        -F 'client_secret=CLIENT-SECRET' \
        -F 'grant_type=authorization_code' \
        -F 'redirect_uri=YOUR-REDIRECT-URI' \
        -F 'code=CODE' \
        https://pyrus.com/oauthtoken

4. Получаем ответ:

{
    "access_token": "fb2e77d.47a0479900504cb3ab4a1f626d174d2d"
}

1С: Предприятие 8

Для работы из Вы можете использовать внешнюю обработку, которая позволяет настроить работу с Pyrus без модификации конфигурации ИБ прикладного решения. Настройку можно произвести через встроенные механизмы типовых конфигураций (дополнительные отчеты и обработки, заполнение табличных частей документов и др.), либо другим способом, если у вас нетиповая конфигурация.

С чего начать?

Прежде чем посылать запросы к Pyrus API, вам нужно авторизоваться проделав следующие шаги:

  • Зарегистрировать приложение в Pyrus. Этот шаг вы выполняете один раз, в результате получаете уникальную пару ClientId и ClientSecret.
  • Получить в коде приложения код авторизации Pyrus при помощи запуска функции модуля ПолучитьAccessToken. Эта функция вызывает диалоговое окно с запросом к пользователю на подтверждение готовности дать доступ вашему приложению к его данным в Pyrus. Если пользователь успешно прошел авторизацию, сервис вернет AccessToken, который нужно использовать для всех будущих вызовов. Подробнее смотрите в примерах, прилагающихся к библиотеке.
  • Теперь вы можете вызывать функции библиотеки, например:
    ПолучитьЗадачу(ИдентификаторЗадачи);

Скачать библиотеку и примеры использования

Скачать библиотеку и пример

В архиве содержится код внешней обработки 1С и пример использования, который создает тестовую задачу в Pyrus.

Технические требования:

  • 1С: Предприятие 8.2 или 8.3
  • обычное приложение, толстый клиент

Как запустить пример?

1. Распакуйте архив в папку C:\1C.PYRUS.COM

2. В 1С: Предприятие запустите внешнюю обработку ТестPyrus.epf

Внешняя обработка

3. В открывшейся форме нажмите на кнопку «Создать задачу»:

Создание задачи

Если Вы создаете первую задачу в рамках запущенной обработки, тогда в открывшемся окне Вам будет предложено подтвердить готовность дать доступ приложению к данным Pyrus (для последующих задач окно подтверждения доступа не открывается). Введите свой логин и пароль в Pyrus и нажмите кнопку «Да (Разрешить доступ)».

Разрешить доступ

4. После этого будет создана задача, и вы увидите подтверждение:

Подтверждение

ПолучитьAccessToken

Вызов методов Pyrus API возможен при обязательной передаче в качестве параметра AccessToken - текстовой строки, идентифицирующей приложение и пользователя, предоставившего приложению доступ в свой аккаунт. Для получения AccessToken из средствами модуля используется функция ПолучитьAccessToken. Параметрами функции является пара Client ID и Client Secret, которая должна быть получена один раз на странице регистрации приложения.

AccessToken хранится на сервере Pyrus достаточно продолжительное время, поэтому нет необходимости запрашивать его перед каждым вызовом процедур обращения к методам API. Следующий пример демонстрирует фрагмент кода , обращающийся к внешней обработке, осуществляющий получение AccessToken и вызов метода создающего задачу в Pyrus.

Обработка = ВнешниеОбработки.Создать("C:\1c.pyrus.com\ВзаимодействиеPyrus.epf");
Если Не ЗначениеЗаполнено(AccessToken) Тогда
    AccessToken = Обработка.ПолучитьAccessToken("demokey", "demosecret");
    Если ЗначениеЗаполнено(AccessToken) Тогда
       Если Лев(AccessToken, 7) = "Ошибка:" Тогда
          Сообщить(AccessToken);
          AccessToken = "";
       КонецЕсли;
    КонецЕсли;
КонецЕсли;
Обработка.ВызватьAddTask(AccessToken);

Вызов методов API

Модуль содержит следующие процедуры, позволяющие вызывать соответствующие методы Pyrus API:

  • ПолучитьЗадачу - вызвать метод GetTask
  • ПолучитьСписокЗадач - вызвать метод GetTaskList
  • СоздатьЗадачу - вызвать метод AddTask
  • СоздатьКомментарий - вызвать метод AddСomment
  • ПолучитьПрофиль - вызвать метод Profile

Модуль содержит несколько предопределенных реквизитов формы, которые имеют одинаковое назначение для всех процедур и используются при их вызове:

  • AccessToken: строка, токен доступа, полученный функцией ПолучитьAccessToken. Важно! Для любой процедуры этот реквизит должен быть установлен в актуальное значение перед ее вызовом.
  • ОтветСервера: соответствие, разобранный в соответствие 1C структурированный результат работы метода Pyrus API. Имена ключей соответствия определяются значениями структуры ответа сервера методов Pyrus API. Значения ключей могут иметь следующие типы:
    • строка
    • число
    • дата
    • булево
    • массив (элементами массива может быть любой из описанных типов)
    • соответствие (рекурсивно)
  • Ошибка: строка, если в ходе выполнения процедуры возникает ошибка, текст ошибки передается в этот реквизит.

ПолучитьЗадачу

Процедура позволяет получить в сведения о задаче Pyrus. Осуществляется вызов метода GetTask.

Параметры:

  • AccessToken (реквизит обработки): строка, токен доступа, полученный функцией ПолучитьAccessToken. Обязательный;
  • ИдентификаторЗадачи: число (TaskId), указывает задачу, сведения о которой необходимо получить. Обязательный.
Результат:
  • ОтветСервера (реквизит обработки): соответствие, содержит описание задачи, ключи соответствия одноименны значениям тела ответа сервера метода GetTask;
  • Ошибка (реквизит обработки): строка, текст ошибки, в случае ее возникновения.

ПолучитьСписокЗадач

Процедура позволяет получить по заданным критериям список описаний задач Pyrus. Осуществляется вызов метода SearchTasks.

Параметры:

  • AccessToken (реквизит обработки): строка, токен доступа, полученный функцией ПолучитьAccessToken. Обязательный;
  • МассивИдентификаторовПроектов: массив чисел (SearchTasksParams.ProjectIds), фильтр по проектам, представляет собой массив идентификаторов проектов;
  • ВключатьЗакрытыеЗадачи: булево (SearchTasksParams.IncludeClosedTasks), флаг включения в поиск закрытых задач;
  • МассивИдентификаторовУчастников: массив чисел (SearchTasksParams.ParticipantIds), фильтр по участникам задачи, представляет собой массив идентификаторов пользователей;
  • ИдентификаторАвтора: число (SearchTasksParams.AuthorId), идентификатор пользователя Pyrus - автора задачи;
  • ИдентификаторИсполнителя: число (SearchTasksParams.ResponsibleId), идентификатор пользователя Pyrus, ответственного по задаче;
  • МаксимальноеКоличествоЗадач: число (SearchTasksParams.MaximumItemsCount), максимальное количество задач, которое вернет сервер, по умолчанию - 50;
  • СодержитПодстроки: строка (SearchTasksParams.IncludeText), включая подстроки;
  • НеСодержитПодстроки: строка (SearchTasksParams.ExcludeText), исключая подстроки, если параметр указан, должен быть указан параметр СодержитПодстроки.
Результат:
  • ОтветСервера (реквизит обработки): соответствие, содержит список найденных задач с их описанием, ключи соответствия одноименны значениям тела ответа сервера метода SearchTasks;
  • Ошибка (реквизит обработки): строка, текст ошибки, в случае ее возникновения.

СоздатьЗадачу

Процедура позволяет создать новую задачу в Pyrus. Осуществляется вызов метода AddTask.

Параметры:

  • AccessToken (реквизит обработки): строка, токен доступа, полученный функцией ПолучитьAccessToken. Обязательный;
  • ТекстЗадачи: строка (AddTaskParams.Text), текст создаваемой задачи. Обязательный;
  • ИдентификаторИсполнителя: число (AddTaskParams.ResponsibleId), идентификатор исполнителя, которому будет назначена задача;
  • МассивИдентификаторовПроектов: массив чисел (AddTaskParams.AddedProjectIds), массив идентификаторов проектов создаваемой задачи;
  • ДатаИсполнения: дата (AddTaskParams.DueDate), срок исполнения задачи;
  • МассивМаршрутизации: массив массивов чисел (AddTaskParams.AddedApprovals), массив шагов согласования, состоящий из массивов идентификаторов пользователей.
Результат:
  • Ошибка (реквизит обработки): строка, текст ошибки, в случае ее возникновения.

СоздатьКомментарий

Процедура позволяет изменить задачу в Pyrus. Осуществляется вызов метода AddComment.

Параметры:

  • AccessToken (реквизит обработки): строка, токен доступа, полученный функцией ПолучитьAccessToken. Обязательный;
  • ИдентификаторЗадачи: число (AddCommentParams.TaskId), указывает задачу, к которой будет добавлен комментарий, является обязательным. Обязательный;
  • ТекстЗадачи: строка (AddCommentParams.Text), текст с формулировкой задачи.
  • ИдентификаторИсполнителя: число (AddCommentParams.ResponsibleId), идентификатор исполнителя, которому будет назначена задача;
  • МассивИдентификаторовПроектов: массив чисел (AddCommentParams.AddedProjectIds), массив идентификаторов проектов изменяемой задачи;
  • ДатаИсполнения: дата (AddCommentParams.DueDate), срок исполнения задачи;
  • МассивМаршрутизации: массив массивов чисел (AddCommentParams.AddedApprovals), массив шагов согласования, состоящий из массивов идентификаторов пользователей;
  • ИзменениеАктивности: строка (AddCommentParams.ActivityAction), изменение активности задачи: Complete - закрыть задачу, MarkAsDuplicate - закрыть, как дубликат, MarkAsIrrelevant - закрыть, как неактуальную, Reopen - переоткрыть задачу;
  • МассивИдентификаторовУдаляемыхПроектов: массив чисел (AddCommentParams.RemovedProjectIds), массив идентификаторов проектов изменяемой задачи;
  • СнятьДатуИсполнения: булево (AddCommentParams.ClearDueDate), флаг снятия срока задачи;
  • МассивУдаляемойМаршрутизации: массив массивов чисел (AddCommentParams.RemovedApprovals), удаляемая маршрутизация;
  • МассивПерезапрашиваемойМаршрутизации: массив массивов чисел (AddCommentParams.RerequestedApprovals), перезапрашиваемая маршрутизация.
Результат:
  • Ошибка (реквизит обработки): строка, текст ошибки, в случае ее возникновения.

ПолучитьПрофиль

Процедура возвращает информацию о пользователе, выдавшем права доступа к Pyrus. Осуществляется вызов метода GetProfile.

Параметры:

  • AccessToken (реквизит обработки): строка, токен доступа, полученный функцией ПолучитьAccessToken. Обязательный.
Результат:
  • ОтветСервера (реквизит обработки): соответствие, содержит разобранный ответ сервера с профилем пользователя, ключи соответствия одноименны значениям тела ответа сервера метода GetProfile;
  • Ошибка (реквизит обработки): строка, текст ошибки, в случае ее возникновения.