# ApiDev - Удобное API КБ

Форматы запросов и ответов к API соответствуют спецификации JSON API.

Точка входа: {site}/api/dev

Для выполнения запросов требуется передавать аутентификационный токен в http-заголовке `X-Auth-Token`. Токены формируются в разделе настроек "Управление API-токенами".

### /data{table_id}

Работа с данными в пользовательских таблицах, адресация таблиц по идентификатору id

#### /data{table_id} get post

get

Получить список записей пользовательской таблицы

post

Создать запись в пользовательской таблице

#### get /data{table_id}

Получить список записей пользовательской таблицы

### URI Parameters

- table_id: required(integer)

  Идентификатор пользовательской таблицы

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

### Query Parameters

- filter=EXPR: (string)

  Задать условие отбора записей с помощью фильтр-выражения. Фильтр-выражение представляет собой композицию функций фильтрации, например

      // Получить список мужчин младше 18 лет
      filter=and(eq(sex,'male'),lt(age,'18'))
      // Отобрать записи с полем f6400 равным "активный" ИЛИ полем f38 больше или равно 50
      filter=or(eq(f6400,'активный'),gte(f38,'50'))

  Доступные функции фильтрации

  Функция | Операция | Пример
  --- | --- | ---
  | Функции сравнения |
  eq | Равно | `eq(f123,'готово')`
  gt | Больше чем | `gt(f201,'54')`
  gte | Больше или равно | `gte(f875,'2011-01-01')`
  lt | Меньше чем | `lt(f3854,'3.14')`
  lte | Меньше или равно | `lte(f550,'17')`
  ne | Не равно | `ne(f28,'архив')`
  | Функции сравнения с массивом значений |
  in | Равно одному из значений из массива | `in(f345,'Активный','Архивный','Завершен')`
  nin | Не равно ни одному значению из массива | `nin(f345,'Завершен','Отменен')`
  | Функции сопоставления строк |
  starts_with | Начинается со | `starts_with(f691,'Mc')`
  ends_with | Заканчивается на | `starts_with(f691,'son')`
  contains | Содержит | `contains(f691,'ушкин')`
  | Функции сопоставления с диапазоном |
  between | Находится в диапазоне | `between(f321,'18','35')`
  | Логические функции |
  and | Логическое И | `and(eq(f76,'male'),lt(f23,'18'))`
  not | Логическое НЕ | `not(gt(f82,'54'))`
  or | Логическое ИЛИ | `or(eq(f39,'male'),eq(f39,'female'))`
  | Специальные функции |
  use_filter | Использовать фильтр КБ | `use_filter(741)`

  ВАЖНО! Не применяется одновременно с заданием фильтра с помощью условий полей.

- filter[FIELD]=OP: (string)

  Задать фильтр отбора записей с помощью условий полей.

  FIELD - имя поля, по которому осуществляется фильтрация

  OP - применяемая операция сравнения: =, <, >, <=, >= (по умолчанию =)

  ВАЖНО! Не применяется одновременно с заданием фильтра через фильтр-выражения.

  Example:

      отобрать записи со значением поля f6400 равным "активный"

      filter[f6400]=активный

      отобрать записи с значением поля f38 меньше 50

      filter[f38]=<50

- page[offset]: (integer - default: 0)

  задать смещение выборки (с какой записи выбирать)

  Example:

      page[offset]=15

- page[limit]: (integer - default: 20)

  Задать количество возвращаемых записей в выборке

  Example:

      page[limit]=10

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": [
    {
      "type": "data371",
      "id": "501",
      "attributes": {
        "f201": "some value",
        "f202": "another value"
      }
    },
    {
      "type": "data371",
      "id": "502",
      "attributes": {
        "f201": "other value",
        "f202": "alter value"
      }
    }
    ]
    }

#### post /data{table_id}

Создать запись в пользовательской таблице

### URI Parameters

- table_id: required(integer)

  Идентификатор пользовательской таблицы

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

### Body

Media type: application/vnd.api+json

Type: object

Properties

- data: required(object)
  - type: required(string)
  - attributes: required(object)

Example:

    {
    "data": {
    "type": "data371",
    "attributes": {
      "f201": "some value",
      "f202": "another value",
      "f222": [
            {
              "file_name": "test.txt",
              "content": "111 222 333"
            },
            {
              "file_name": "image.png",
              "content": <base64_content>,
              "binary": true
            }
          ]

    }
    }
    }

## HTTP status code 201

### Body

Media type: application/vnd.api+json

Type: any

Media type: type

Type: object

Properties

- data: required(object)
  - type: required(string)

    имя ресурса (таблицы)

  - id: required(string)

    идентификатор записи

  - attributes: required(object)

    поля записи и их значения

Example:

    {
    "data": {
    "type": "data371",
    "id": "501",
    "attributes": {
      "f201": "some value",
      "f202": "another value"
    }
    }
    }

#### /data{table_id}/{ID} get patch delete

Работа с отдельными записями в пользовательской таблице

get

Получить запись из пользовательской таблицы

patch

Изменить запись в пользовательской таблице

delete

Удалить запись в пользовательской таблице

#### get /data{table_id}/{ID}

Получить запись из пользовательской таблицы

### URI Parameters

- table_id: required(integer)

  Идентификатор пользовательской таблицы

- ID: required(integer)

  Идентификатор записи

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Properties

- data: required(object)
  - type: required(string)

    имя ресурса (таблицы)

  - id: required(string)

    идентификатор записи

  - attributes: required(object)

    поля записи и их значения

Example:

    {
    "data": {
    "type": "data371",
    "id": "501",
    "attributes": {
      "f201": "some value",
      "f202": "another value"
    }
    }
    }

## HTTP status code 404

Запись с указанным ID не существует

### Body

Media type: application/vnd.api+json

Type: object

Properties

- errors: required(string)

Example:

    {
    "errors": {
    "title": "Resource Not Found",
    "status": 404,
    "details": "Resource ID not found"
    }
    }

#### patch /data{table_id}/{ID}

Изменить запись в пользовательской таблице

### URI Parameters

- table_id: required(integer)

  Идентификатор пользовательской таблицы

- ID: required(integer)

  Идентификатор записи, которую нужно изменить

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

### Body

Media type: application/vnd.api+json

Type: object

Properties

- data: required(object)
  - type: required(string)

    имя ресурса (таблицы)

  - id: required(string)

    идентификатор записи, которую нужно изменить

  - attributes: required(object)

    поля записи и их значения

Example:

    {
    "data": {
    "type": "data371",
    "id": "501",
    "attributes": {
      "f202": "new value",
      "f222": [
            {
              "file_name": "test.txt",
              "content": "111 222 333"
            },
            {
              "file_name": "image.png",
              "content": <base64_content>,
              "binary": true
            }
          ]
    }
    }
    }

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Properties

- data: required(object)
  - type: required(string)

    имя ресурса (таблицы)

  - id: required(string)

    идентификатор записи

  - attributes: required(object)

    поля записи и их значения

Example:

    {
    "data": {
    "type": "data371",
    "id": "501",
    "attributes": {
      "f201": "some value",
      "f202": "another value"
    }
    }
    }

#### delete /data{table_id}/{ID}

Удалить запись в пользовательской таблице

### URI Parameters

- table_id: required(integer)

  Идентификатор пользовательской таблицы

- ID: required(integer)

  Идентификатор записи

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 204

### /table

Получить информацию о структуре пользовательских таблиц, о правах доступа к таблице

#### /table get

get

Получить список пользовательских таблиц и права доступа к ним

#### get /table

Получить список пользовательских таблиц и права доступа к ним

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": [
    {
      "type": "table",
      "id": "20",
      "attributes": {
        "table_name": "Документы",
        "category_id": 2,
        "category_sequence_number": 6,
        "full_name": "Общие документы"
      },
      "meta": {
        "access": {
          "create": true,
          "read": false,
          "update": false,
          "delete": true,
          "archive": true,
          "bed": true,
          "print": false,
          "sms": false,
          "send": false,
          "free_sms_template": false,
          "free_mail_template": false,
          "standart_template": true
        }
      }
    },
    {
      "type": "table",
      "id": "42",
      "attributes": {
        "table_name": "Контрагенты",
        "category_id": 1,
        "category_sequence_number": 1,
        "full_name": "Компании"
      },
      "meta": {
        "access": {
          "create": true,
          "read": false,
          "update": false,
          "delete": true,
          "archive": true,
          "bed": true,
          "print": false,
          "sms": false,
          "send": false,
          "free_sms_template": false,
          "free_mail_template": false,
          "standart_template": true
        }
      }
    }
    ]
    }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

#### /table/{ID} get

Получить информацию о пользовательской таблице с указанным ID

get

Получить информацию о пользовательской таблице

#### get /table/{ID}

Получить информацию о пользовательской таблице

### URI Parameters

- ID: required(integer)

  Идентификатор таблицы

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

### Query Parameters

- include=fields: (string)

  Получить информацию о полях пользовательской таблицы

- include=fiters: (string)

  Получить информацию о фильтрах пользовательской таблицы

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": {
    "type": "table",
    "id": "20",
    "attributes": {
      "table_name": "Документы",
      "category_id": 2,
      "category_sequence_number": 6,
      "full_name": "Общие документы"
    },
    "meta": {
      "access": {
        "create": true,
        "read": false,
        "update": false,
        "delete": true,
        "archive": true,
        "bed": true,
        "print": false,
        "sms": false,
        "send": false,
        "free_sms_template": false,
        "free_mail_template": false,
        "standart_template": true
      }
    }
    }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

### /user

Получение информации о пользователях

#### /user get

get

Получить список пользователей

#### get /user

Получить список пользователей

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": [
    {
      "type": "user",
      "id": "12",
      "attributes": {
        "fio": "Иванов Сергей Петрович",
        "group_id": 2,
        "arc": 0
      }
    },
    {
      "type": "user",
      "id": "13",
      "attributes": {
        "fio": "Силаньтев Владимир",
        "group_id": 2,
        "arc": 0
      }
    }
    ]
    }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

#### /user/{ID} get

Получить информацию о пользователе с идентификатором ID

get

Получить информацию о пользователе

#### get /user/{ID}

Получить информацию о пользователе

### URI Parameters

- ID: required(integer)

  Идентификатор пользователя

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": {
    "type": "user",
    "id": "12",
    "attributes": {
      "fio": "Иванов Сергей Петрович",
      "group_id": 2,
      "arc": 0
    }
    }
    }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

### /group

Получение информации о группах пользователей

#### /group get

get

Получить список групп пользователей

#### get /group

Получить список групп пользователей

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": [
    {
      "type": "group",
      "id": "2",
      "attributes": {
        "name": "Менеджеры"
      }
    },
    {
      "type": "group",
      "id": "777",
      "attributes": {
        "name": "Клиенты"
      }
    }
    ]
    }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

#### /group/{ID} get

Получить информацию о группе с идентификатором ID

get

Получить информацию о группе пользователей

#### get /group/{ID}

Получить информацию о группе пользователей

### URI Parameters

- ID: required(integer)

  Идентификатор группы

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
    "data": {
    "type": "group",
    "id": "2",
    "attributes": {
      "name": "Менеджеры"
    }
    }
    }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

### /file

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

#### /file/{TableID}/{FieldID}/{LineID}/{FileName} get

get

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

#### get /file

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

### URI Parameters

- TableID: required(integer)

  Идентификатор таблицы

- FieldID: required(integer)

  Идентификатор поля таблицы, содержащего файл

- LineID: required(integer)

  Идентификатор записи в таблице, содержащей файл

- FileName: required(string)

  Название файла

### Headers

- Content-Type: required(string)

  Example:

      application/vnd.api+json

- X-Auth-Token: required(string)

  Example:

      vV3RSKE7AfBGrPKryBry2pnG0knK1NLbt765y0Aji2pOHhHV

## HTTP status code 200

### Body

Media type: application/vnd.api+json

Type: object

Example:

    {
          "data": {
              "type": "file",
              "attributes": {
                  "name": "photo-01-01-2023.jpg",
                  "content": "iVBORw0KGgoAAAANSUhEUgAAAxEAAAJICAIAAACR8/66AAAgAElE...",
                  "md5sum": "b60743646b1e0730dfce9404ba77e0a0"
              }
          }
      }

## HTTP status code 404

Запрашиваемый объект не обнаружен

## HTTP status code 443

Нет прав доступа к запрашиваемому объекту

### /hello

Тестовый сервис приветствия

Публичный доступ, не требует аутентификации

#### /hello/{name} get

get

Выводит приветствие для указанного имени: "Hello, {name}!"

#### get /hello/{name}

Выводит приветствие для указанного имени: "Hello, {name}!"

### URI Parameters

- name: required(string)

## HTTP status code 200

### Body

Media type: text/plain

Type: string

Example:

    Hello, world!