api:fields

Формат полей формы

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

{
  "id": 15,
  "name": "Summary",
  "type": "text",
  "value": "Printer does not print",
  "info": {
    "immutable_step": 1,
    "required_step": 1
  }
}

В зависимости от вызываемого метода передается и возвращается только часть свойств:
Запрос id name type value info
GET /forms
GET /forms/{form-id}/register
GET /tasks/{task-id}
POST /tasks/{task-id}/comments *
POST /tasks *

* Необходимо указать хотя бы один из этих параметров

Типы полей и примеры

Бывают простые и составные типы полей. В качестве значения простые типы принимают значения стандартных типов данных (строка, число, дата), составные — JSON объект.

Простые типы

Тип Описание Пример
text
"value": "IT Conference"
money
"value": 1365.27
number
"value": 157.2134
date Формат даты:
YYYY-MM-DD
"value": "2017-03-16"
time Формат времени: HH:mm
"value": "17:26"
checkmark Возможные значения:
  • checked
  • unchecked
"value": "checked"
due_date Формат даты:
YYYY-MM-DD
"value": "2017-03-16"
due_date_time Формат даты:
YYYY-MM-DDThh:mm:ssZ
"value": "2017-03-16T14:53:23Z"
email
"value": "consumer@mycompany.com"
phone
"value": "+7 800 555 3565"
flag Возможные значения:
  • none
  • checked
  • unchecked
"value": "unchecked"
step только для чтения
"value": 1
status только для чтения
Возможные значения:
  • open
  • closed
"value": "open"
creation_date только для чтения
Формат даты:
YYYY-MM-DD
возвращается дата по UTC
"value": "2017-03-18"
note только для чтения
"value": "This is a tooltip"
Для записи в примитивный тип необходимо передать идентификатор id или имя поля name, а также новое значение в поле value.

Составные типы

catalog
Чтение:

"value": {
  "item_id": 51234
  "headers": [
    "Vendor Name", 
    "Vendor Code"
  ],
  "values": [
    "GE", 
    "123"
  ]
}

Запись:

Для записи значения можно передать как идентификатор элемента в каталоге:
"value": {
  "item_id": 23
}
так и название элемента:
"value": {
  "item_name": "GE"
}

file
Чтение:

"value": [{
  "id": "17563",
  "name": "S15294-16.pdf",
  "size": 541512,
  "md5": "202cb962ac59075b964b07152d234b70",
  "url": "https://api.pyrus.com/files/17563"
}]

Запись:

"value": [
  "66fcc656-9182-4d4a-9d1f-ece882cd12cd",
  "3b5ff13b-e561-4b56-9db2-bea4f8677429"
]
Загрузить файл и получить его идентификатор можно с помощью метода files/upload.

person
Чтение:

"value": {
  "id": 1730,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "Jane.Doe@gmail.com"
}

Запись:

Для записи можно передать как идентификатор пользователя:
"value": {
  "id": 1730,
}
так и его email:
"value": {
  "email": "Jane.Doe@gmail.com",
}

author (только для чтения)
Чтение:

"value": {
  "id": 1730,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "Jane.Doe@gmail.com"
}

table
Чтение:

"value": [
    {
    "row_id": 0,
    "cells": [
      {
        "id": 6,
        "type": "date",
        "name": "Date",
        "value": "2017-08-26"
      },
      {
        "id": 9,
        "type": "money",
        "name": "Amount",
        "value": 10000
      }
    ]
  },
  {
    "row_id": 1,
    "cells": [
    {
      "id": "6",
      "type": "date",
      "name": "Date",
      "value": "2017-08-27"
    },
    {
      "id": 9,
      "type": "money",
      "name": "Amount",
      "value": 306.25
    }
  ]}
]

Запись:

"value": [{
    "row_id": 0,
    "delete": true
  },
  {
  "row_id": 1,
  "cells": [
    {
      "id": 9,
      "value": 351.25
    },
    {
      "id": 6,
      "value": "2017-08-21"
    }
  ]
}]

multiple_choice
Чтение:

"value": {
  "choice_ids": [5],
  "fields": [
    {
      "id": 6,
      "type": "text",
      "name": "Comment",
      "value": "Additional information about choice"
    },
    {
      "id": 9,
      "type": "number",
      "name": "Quantity",
      "value": 15
    }
  ]
}

Запись:

"value": {
    "choice_ids": [5]
    "fields": [
      {
        "id": 9,
        "value": 1
      }
    ]
  }

title
Чтение:

"value": {
  checkmark: "checked",
  "fields": [
    {
      "id": "3",
      "type": "date",
      "name": "Date",
      "value": "2017-08-19"
    },
    {
      "id": "4",
      "type": "text",
      "name": "Description",
      "value": "My issue"
    }
  ]
}

Запись:

"value": {
  "fields": [
    {
      "id": 4,
      "value": "It is not an issue"
    }
  ]
}

form_link
Чтение:

"value": {
  "task_ids": [1573],
  "subject": "Expense report"
}

Запись:

"value": {
  "task_ids" : [1753]
}

project (устарело, только для чтения)
Чтение:

"value": {
  "projects: [
    {
      "id": 1,
      "name": "Root Project"
    },
    {
      "id": 3,
      "name": "Child Project",
      "parent": {
        "id": 2,
        "name": "Another root project"
      }
    }
  ]
}

Дополнительная информация о поле

Объект info может содержать 2 ключа для всех типов полей:

  • required_step — указывает номер шага, начиная с которого поле становится обязательным для заполнения;
  • immutable_step — указывает номер шага, начиная с которого пользователь не может изменять значение поля.

Нумерация шагов начитается с единицы.

Помимо перечисленных ключей, объект info в зависимости от типа будет содержать один из дополнительных ключей, описанных ниже:

Тип Ключ Пример
multiple_choice options
"options": [
  {
    "choice_id": 0,
    "choice_value": "Not Set"
  },
  {
    "choice_id": 1,
    "choice_value": "Yes",
    "fields": {
      "id": 4,
      "type": "text",
      "name": "Reason"
    }
  },
  {
    "choice_id": 2,
    "choice_value": "No",
  }
]
catalog catalog_id
"catalog_id": 165
table columns
"columns": [
  {
    "id": 9,
    "type": "money",
    "name": "Amount"
  },
  {
    "id": 6,
    "type": "date",
    "name": "Date"
  }
]
title fields
"fields": [
  {
    "id": 9,
    "type": "money",
    "name": "Amount"
  },
  {
    "id": 6,
    "type": "date",
    "name": "Date"
  }
]
form_link form_id
"form_id": 1453

Была ли эта статья полезной?

Да, спасибо! Нет, остался вопрос