Описание команд и примеры использования API Интеграм

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

Терминология

В конструкторе есть понятие термин — это любой термин, которым оперирует разработчик или пользователь.
Примеры терминов: Пользователь, Клиент, Адрес, Статус. Пользователь работает с таблицами данных, поэтому он чаще использует слово таблица для определения объекта действия, например: таблица Пользователь или таблица Клиент.
Термины могут быть подчинены друг другу и связаны с другими терминами, например: у Клиента есть Адрес и Телефон. В этом случае таблица клиентов будет выглядеть так:
При этом пользователь назовет все эти термины колонками таблицы Клиент, в то время как программист скажет, что Адрес и Телефон — это реквизиты термина Клиент.
Далее мы будем использовать тот или иной вариант названий, исходя из удобства в данной ситуации, а разработчик должен быть готов к обоим вариантам названий, чтобы понимать пользователя.

Общие правила

Обращение по API выполняется по адресу сервиса с указанием вашей базы, действия и ID объекта, над которым производится действие, если это применимо. Также необходимо указать параметр JSON, чтобы сервис понял, что это вызов API, и вернул результат в JSON:
integram.io/{база}/{действие}/{id}?JSON=1
Обязательный параметр действие может иметь два префикса для команд на изменение данных:
_d_* — изменение структуры данных (DDL, команды Редактора структуры);
_m_* — изменение самих данных (DML, команды базового интерфейса);
Некоторые команды (например, xsrf, metadata, exit) используются только по API, поэтому для них нет необходимости указывать параметр JSON, например, как для метаданных термина Роль:
https://integram.io/apix/metadata/42
Далее, для унификации, все эти вызовы будут приведены в формате CURL:
curl --location 'integram.io/apix/metadata/42'
Ответ придет в формате JSON с описанием структуры таблицы Роль, где reqs — это описание её колонок:
{
    "id": "42",
    "up": "0",
    "type": "3",
    "val": "Роль",
    "unique": "1",
    "reqs": [
        {
            "num": 1,
            "id": "117",
            "val": "Объекты",
            "type": "5",
            "arr_id": "116"
        },
        {
            "num": 2,
            "id": "154",
            "val": "Меню",
            "type": "3",
            "arr_id": "151"
        },
        {
            "num": 3,
            "id": "135",
            "val": "Описание",
            "type": "12"
        }
    ]
}

Список команд API

В таблице приведен список команд, допустимые методы, применимость параметра ID и описание других параметров.

Авторизация и управление базами

Авторизация

Авторизация пользователя доступна по API, если вы регистрировались по почте или задали себе пароль после регистрации через соц. сети (Google и другие):
curl --location 'https://integram.io/apix/auth?JSON=1' \
--form 'login="apiuser"' \
--form 'pwd="************"'
В ответ придет JSON с токенами XSRF и авторизационным: 
{
    "_xsrf": "cd4b6417a3940ed4a84h074d",
    "token": "ea15dcc3a8cae93e8f5e17e25b6710",
    "id": "632",
    "msg": ""
}
Токен авторизации следует передавать с каждым запросом в заголовке Authorization:
curl --location 'integram.io/apix/metadata/42' \
--header 'Authorization: ea15dcc3a8cae93e8f5e17e25b6710'
Токен _xsrf следует передавать с каждым POST-запросом на изменение данных или структуры, как показано здесь:
curl --location 'https://integram.io/apix/_d_new?JSON=1' \
--form 't="3"' \
--form 'val="Клиент"' \
--header 'Authorization: ea15dcc3a8cae93e8f5e17e25b6710' \
--form '_xsrf="1cb413634d074d3804ed48"'
В дальнейших примерах, для компактности, мы будем опускать эти параметры: токен авторизации и xsrf.

Basic HTTP Authentication

Также возможен вариант более простой авторизации, так называемая Basic HTTP Authentication, когда имя и пароль передаются в заголовке каждого запроса:
Authorization: Basic Username:Password
По RFC7617 фрагмент Username:Password должен быть закодирован в BASE64, однако, для простоты допускается отправить его без кодирования, это тоже сработает. Пример использования такой авторизации приведен здесь.

Токены, ID и имя пользователя

Когда у вас есть токен, можно узнать остальную информацию о пользователе и сессии, вызвав команду xsrf:
curl --location 'https://integram.io/apix/xsrf'
Ответ будет примерно таким, и вы можете использовать эту информацию:
{
    "_xsrf": "cd4b6417a3940ed4a84h074d",
    "token": "ea15dcc3a8cae93e8f5e17e25b6710",
    "user": "apiuser",
    "role": "api",
    "id": "632",
    "msg": ""
}

Список баз

После авторизации в личном кабинете (ЛК) — базе my — вам доступны операции с вашими базами. Для этого нужно вызвать отчет с ID 313 и передать параметр JSON_KV:
curl --location 'https://integram.io/my/report/313?JSON_KV=1'
В ответ будет получен JSON в формате Ключ:Значение со списком баз, созданных в этом ЛК. В примере ниже видно 2 базы: test и redes.
[
    {
        "User": null,
        "Email": "alex@gmail.com",
        "Name": "Alexey Samuel",
        "Phone": "",
        "Date": "08.07.2024",
        "Notes": "",
        "Picture": "https://lh3.googleusercontent.com/a/Agg8cJ2WhxugeQNadTqoZaYxbORgdTEq_I-FRg=6-c",
        "DBID": "178652",
        "DB": "test",
        "Balance": "0",
        "Bonus": "",
        "Referrals": "",
        "Template": "RU",
        "Description": "",
        "Count": "0",
        "Plan": "Startup",
        "Plan date": "23.04.2025",
        "PlanID": "1147"
    },
    {
        "User": null,
        "Email": "alex@gmail.com",
        "Name": "Alexey Samuel",
        "Phone": "",
        "Date": "08.07.2024",
        "Notes": "",
        "Picture": "https://lh3.googleusercontent.com/a/Agg8cJ2WhxugeQNadTqoZaYxbORgdTEq_I-FRg=6-c",
        "DBID": "195822",
        "DB": "redes",
        "Balance": "0",
        "Bonus": "",
        "Referrals": "",
        "Template": "ru",
        "Description": "",
        "Count": "0",
        "Plan": "Startup",
        "Plan date": "23.04.2025",
        "PlanID": "1147"
    }
]

Создать базу

Для создания базы в данном ЛК следует выполнить запрос метода _new_db с параметрами db — имя базы и template — шаблон базы.
curl --location 'https://integram.io/my/_new_db/?JSON=1&db=apiman&template=RU'
В случае успеха будет ответ с идентификатором созданной базы:
{
    status: "Ok",
    id: 221756
}

Метаданные

Базовые типы

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

Описание данных

Команда для описания всех терминов и их свойств и связей — metadata. Будучи вызвана без параметров, она возвращает полное описание вашей базы:
curl --location 'https://integram.io/apix/metadata?JSON=1'
Если указать параметр ID, то в ответ вернется только описание термина с указанным ID, например, Пользователь:
curl --location 'https://integram.io/apix/metadata/18?JSON=1'
Здесь виден тип колонки Пользователь — 3 (SHORT) и его реквизиты со своими свойствами и атрибутами.
[
    {
        "id": "18",
        "up": "0",
        "type": "3",
        "val": "Пользователь",
        "unique": "1",
        "reqs": [
            {
                "num": 1,
                "id": "115",
                "val": "Роль",
                "type": "3",
                "ref": "42",
                "ref_id": "114",
                "attrs": ":!NULL:164"
            },
            {
                "num": 2,
                "id": "41",
                "val": "Email",
                "type": "3",
                "attrs": ":!NULL:"
            },
            {
                "num": 3,
                "id": "30",
                "val": "Телефон",
                "type": "3"
            },
            {
                "num": 4,
                "id": "156",
                "val": "Дата",
                "type": "9",
                "attrs": "[TODAY]"
            },
            {
                "num": 5,
                "id": "33",
                "val": "Имя",
                "type": "3"
            },
            {
                "num": 6,
                "id": "39",
                "val": "Примечание",
                "type": "12"
            },
            {
                "num": 7,
                "id": "38",
                "val": "Фото",
                "type": "10"
            },
            {
                "num": 8,
                "id": "124",
                "val": "Activity",
                "type": "4"
            },
            {
                "num": 9,
                "id": "130",
                "val": "Secret",
                "type": "3"
            },
            {
                "num": 10,
                "id": "20",
                "val": "Password",
                "type": "6"
            },
            {
                "num": 11,
                "id": "125",
                "val": "Token",
                "type": "6"
            },
            {
                "num": 12,
                "id": "40",
                "val": "xsrf",
                "type": "6"
            },
            {
                "num": 13,
                "id": "647",
                "val": "Тег",
                "type": "3",
                "ref": "616",
                "ref_id": "617",
                "attrs": ":MULTI:"
            }
        ]
    }
]
Вот расшифровка некоторых значений:
id — ID термина или его колонки
up — родительский элемент, у метаданных всегда 0
type — базовый тип термина
val — значение термина
unique — признак уникальности экземпляров термина
num — номер по порядку среди равных
ref — ID таблицы справочника для ссылочного поля
ref_id — ID ссылки на справочник для ссылочного поля
Атрибуты — attrs — бывают следующие:
:!NULL: — признак обязательности заполнения
:MULTI: — признак множественного выбора у ссылочного поля
:LABEL: — псевдоним для ссылочного поля
Всё, что не включено в двоеточия, является значением по умолчанию для этого поля.

Таблицы

Список таблиц

Список таблиц, который видно в меню Таблицы, можно получить командой dict:
curl --location 'https://integram.io/apix/dict?JSON=1'
В ответе будет список таблиц вашей базы и их идентификаторы, по которым эти таблицы можно открыть.
{
    "18": "Пользователь",
    "22": "Запрос",
    "29": "Формат",
    "42": "Роль",
    "47": "Доступ",
    "63": "Функция",
    "65": "Итог",
    "137": "Форма",
    "269": "Настройка",
    "300": "Категории",
    "301": "Вид",
    "515": "Опорос",
    "616": "Тег"
}
Содержимое таблицы можно посмотреть, вызвав метод object с указанием ID таблицы, полученного из метода dict, например, Роль — 42:
curl --location 'https://integram.io/apix/object/42?JSON_DATA=1'
Обратите внимание на использование параметра JSON_DATA вместо JSON!
В ответе будет содержимое таблицы Роль в виде массива объектов (строк) в таком формате:
i: ID записи,
u: ID родителя,
o: порядок среди равных,
r: ["значение первой колонки", "значение второй колонки", ...]
[
  {
    "i": 145,
    "u": 1,
    "o": 1,
    "r": [
      "admin",
      "3",
      "6",
      ""
    ]
  },
  {
    "i": 164,
    "u": 1,
    "o": 1,
    "r": [
      "user",
      "2",
      "",
      ""
    ]
  },
  {
    "i": 512,
    "u": 1,
    "o": 1,
    "r": [
      "api",
      "2",
      "",
      ""
    ]
  },
  {
    "i": 626,
    "u": 1,
    "o": 1,
    "r": [
      "guest",
      "1",
      "",
      ""
    ]
  }
]
В текущей версии сервиса при использовании JSON вместо JSON_DATA структура ответа будет другая, более сложная, и вы можете увидеть в результате запроса ключи, начинающиеся с амперсанда (&), например, "&object_reqs". Такой формат оставлен для обратной совместимости некоторых решений и будут выведены в ближайшее время. Рекомендуем использовать JSON_DATA.

Создать таблицу

Команда на создание термина _d_new создает таблицу из 1 колонки, к которой далее мы можем добавить ещё колонки, используя другие термины. Не забываем передать токен _xsrf как POST-параметр:
curl --location 'https://integram.io/apix/_d_new?JSON=1' \
--form 't="3"' \
--form 'val="Клиент"'
В ответ придет ID созданного термина Клиент (новой таблицы) в параметре obj — 641:
{
    "id": "",
    "obj": 641,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}

Добавить колонку

Добавление колонки состоит из двух действий:
  1. Создание термина, который будет новой колонкой
  2. Добавление термина в качестве колонки к таблице
Вы можете пропустить первый шаг, если нужный термин уже есть. Также вы можете использовать один термин в качестве колонки у разных таблиц.
Итак, создаем новый термин ИНН, как мы делали это для новой таблицы:
curl --location 'https://integram.io/apix/_d_new?JSON=1' \
--form 't="3"' \
--form 'val="ИНН"'
В ответ получаем его идентификатор — 642:
{
    "id": "",
    "obj": 642,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
Теперь используем метод _d_req для добавления термина ИНН (642) как колонки таблице Клиент (641):
curl --location 'https://integram.io/apix/_d_req/641?JSON=1' \
--form 't="642"'
Получим ответ с ID новой колонки таблицы — 643
{
    "id": 643,
    "obj": 641,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
В меню Таблицы -> Клиент мы видим эти коды: код таблицы, который виден в первой колонке и в адресе страницы, а также код добавленной нами колонки ИНН:

Добавить колонку-справочник

Добавление колонки состоит из трёх действий:
  1. Создание термина, который будет новой колонкой
  2. Создание ссылки на этот термин
  3. Добавление ссылки на термин в качестве колонки к таблице
Вы можете пропустить первый и второй шаги, если нужный термин и ссылка на него уже уже есть. Вы можете несколько раз использовать один и тот же ссылочный термин в качестве колонки у одной таблицы, назначив этим колонкам псевдонимы.
Создаем новый термин Категория, как мы делали это для новой таблицы:
curl --location 'https://integram.io/apix/_d_new?JSON=1' \
--form 't="3"' \
--form 'val="Категория"'
В ответ получаем его идентификатор — 644:
{
    "id": "",
    "obj": 644,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
Теперь создаем термин-ссылку на термин Категория:
curl --location 'https://integram.io/apix/_d_ref/644?JSON=1'
Получаем ID ссылки (645) на термин Категория (644):
{
    "id": 644,
    "obj": 645,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
Теперь используем метод _d_req для добавления ссылки на Категорию (645) как колонки таблице Клиент (641):
curl --location 'https://integram.io/apix/_d_req/641?JSON=1' \
--form 't="645"'
В ответ получаем ID этой новой колонки — ссылки на Категорию:
{
    "id": 646,
    "obj": 641,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
В меню Таблицы -> Клиент мы видим новую колонку — ссылка на Категорию:

Колонка-справочник с мульти-выбором

Если нам требуется сделать справочное значение с мульти-выбором, необходимо использовать метод _d_multi, который ставит и снимает признак множественного выбора у колонки.
curl --location 'https://integram.io/apix/_d_multi/646?JSON=1'
Если нам требуется сделать справочное значение с мульти-выбором, необходимо использовать метод _d_multi, который ставит и снимает признак множественного выбора у колонки.
Успешный ответ будет таким:
{
    "id": 646,
    "obj": "641",
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
Колонка с мульти-выбором позволяет добавить несколько списочных значений в одно поле, как поле Тег на этом рисунке:

Удалить колонку

Для удаления колонки используется метод _d_del_req с указанием ID удаляемой колонки.
Например, нам надо удалить колонку ИНН:
curl --location 'https://integram.io/apix/_d_ord/643?JSON=1'
Как вы видите, эта колонка в таблице заполнена данными, и в этом случае мы получим ответ об ошибке:
[
    {
        "error": "Вы хотите удалить реквизит у типа при наличии этого реквизита у экземпляров (всего: 1)!"
    }
]
В этом случае, если мы уверены, что колонку надо удалить вместе с данными, мы передаем параметр forced:
curl --location 'https://integram.io/apix/_d_del_req/643?JSON=1' \
--form 'forced="1"'
Колонка будет удалена вместе с данными, и мы получим ответ с ID таблицы, в которой была эта колонка:
{
    "id": "641",
    "obj": "641",
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
Внимание! После удаления колонки, сам термин не удаляется, и его можно использовать как колонку в другой таблице или даже как самостоятельную таблицу. Это сделано, чтобы не пересоздавать заново все термины колонок при создании другой таблицы вместо удаленной. Термин виден как таблица из одного поля в меню Таблицы и его можно окончательно удалить.

Переместить колонку

Колонки в таблице нумеруются с 0, и нулевую колонку перемещать нельзя. Для изменения порядка колонок в таблице используется метод _d_ord с указанием ID колонки и её нового порядка.
Для перемещения колонки указываем её новый порядок в параметре order:
curl --location 'https://integram.io/apix/_d_ord/648?JSON=1' \
--form 'order="1"'
Колонка будет перемещена на первую позицию, и мы получим ответ с её ID:
{
    "id": 648,
    "obj": 648,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}

Удалить таблицу

Для удаления таблицы (термина) используется команда _d_del с указанием удаляемой таблицы. Если таблица непустая, то её необходимо сначала очистить, о чем будет выдано сообщение. Например, мы можем удалить неиспользуемый термин ИНН, который всё ещё виден среди таблиц:
curl --location 'https://integram.io/apix/_d_del/642?JSON=1'
Пустая таблица будет удалена, и мы получим ответ её ID:
{
    "id": 642,
    "obj": null,
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}

Задать псевдоним

Колонке со справочным полем можно задать псевдоним. Это бывает удобно, когда в таблице есть несколько справочных полей, ссылающихся на одну таблицу. Например: у задачи может быть Автор, Исполнитель и Контролер, и все они будут выбираться из справочника (таблицы) Пользователь. В этом случае им можно задать соответствующие псевдонимы вместо трёх одинаковых колонки Пользователь.
Псевдоним задается командой _d_alias с параметром ID колонки. Например, переименуем Тег в Метка:
curl --location 'https://integram.io/apix/_d_alias/648?JSON=1' \
--form 'val="Метка"'
В ответ получим ID таблицы:
{
    "id": "641",
    "obj": "641",
    "next_act": "edit_types",
    "args": "ext",
    "warnings": ""
}
В таблице имя колонки тоже изменится:

Справочные поля

Любая таблица, в том числе подчиненная, может быть использована как справочник. Значение в справочной колонке хранится как ID записи из соответствующего справочника. На форме редактирования записи справочные поля выглядят примерно так, как Метка и Категория:
Обратите внимание, что поле Метка имеет множественный выбор, в то время как поле Категория позволяет выбрать только одно значение.

Запросить справочник

Для запроса справочных значений используется команда _ref_reqs с опциональным указанием ID записи, для которой запрашивается справочник:
curl --location 'https://integram.io/apix/_ref_reqs/646?JSON=1&id=649'
В ответ будут получены значения из справочника, например:
{
    "650": "Лид",
    "660": "Клиент",
    "661": "ЧС"
}
Необязательный параметр ID записи лучше передавать всегда, потому что он может использоваться Интеграмом в том случае, когда в метаданных указан запрос как значение по умолчанию для данного поля. При вычислении запроса могут быть использованы любые служебные слова и контекстные переменные, в том числе и ID записи.

Выбрать значение

При выборе значения из списка его можно сохранить, используя команду _m_set с ID редактируемой записи и параметром t{ID колонки}, равным ID выбранного значения. Например, ID колонки Категория — 646, согласно метаданным, и для выбора Категории Клиент (ID 660) у клиента с ID 649 следует отправить такую команду:
curl --location 'https://integram.io/apix/_m_set/649?JSON=1' \
--form 't646="660"'
В ответ будет получен ID созданного или измененного значения ссылки (658):
{
    "id": "658",
    "obj": 649,
    "next_act": "nul",
    "args": "",
    "warnings": ""
}
Таким образом можно задать значение как для справочника с единственным выбором, так и для множественного. Если такой элемент множественного выбора уже присутствует, то мы получим в ответ его ID и никаких изменений сделано не будет.

Удалить значение

Определить тип выпадающего списка можно по атрибуту :MULTI:, полученному в метаданных таблицы. Если атрибут есть, то это список с множественным выбором.
Единственное значение из выпадающего списка
Удалить значение выпадающего списка с единственным выбором можно, отправив « » (пробел) в качестве значения колонки:
curl --location 'https://integram.io/apix/_m_set/649?JSON=1' \
--form 't646=" "'
Значения из списка с множественным выбором
Для удаления значение списка с множественным выбором следует вызвать метод _m_del с ID удаляемой ссылки:
curl --location 'https://integram.io/apix/_m_del/654?JSON=1'

Дополнить справочник

При наличии доступа к справочнику вы можете добавлять туда значения командой _m_new, которая подробно описана здесь. Параметры команды мы можем узнать из метаданных Клиента:
curl --location 'integram.io/apix/metadata/641'
Метаданные выглядят вот так, и здесь мы видим ключ "ref", который указывает на ID таблицы, которая используется как справочник.
{
    "id": "641",
    "up": "0",
    "type": "3",
    "val": "Клиент",
    "unique": "0",
    "reqs": [
        {
            "num": 1,
            "id": "648",
            "val": "Тег",
            "type": "3",
            "ref": "616",
            "ref_id": "617",
            "attrs": ":MULTI::ALIAS=Метка:"
        },
        {
            "num": 2,
            "id": "646",
            "val": "Категория",
            "type": "3",
            "ref": "644",
            "ref_id": "645"
        }
    ]
}
То есть, для добавления записи в справочник Категория мы используем ID 644, а также передаем параметры:
t644 — значение записи
up=1 — родитель записи, для справочников это, как правило, 1
curl --location 'https://integram.io/apix/_m_new/644?JSON=1' \
--form 't644="Бывший"' \
--form 'up="1"'
Будет такой ответ, в котором мы видим ID созданной записи — 662, который мы немедленно можем использовать в справочнике:
{
    "id": 662,
    "obj": 662,
    "ord": 1,
    "next_act": "object",
    "args": "",
    "val": "Бывший"
}
В самом справочнике, при запросе его командой _ref_reqs, мы тоже видим это значение:
{
    "650": "Лид",
    "660": "Клиент",
    "661": "ЧС",
    "662": "Бывший"
}

Записи

Запросить список

Для любой таблицы из списка таблиц мы можем запросить набор записей, например, таблица клиентов, её ID 641:
curl --location 'https://integram.io/apix/object/641?JSON=1'
В ответе каждая строчка будет представлена объектом, для которого указан ID, родитель (u), порядок среди равных (o) и набор значений колонок таблицы (r):
[
  {
    "i": 649,
    "u": 1,
    "o": 1,
    "r": [
      "АО Ромашка",
      "Летняя, 21",
      "8(555)0123456"
    ]
  },
  {
    "i": 668,
    "u": 1,
    "o": 1,
    "r": [
      "ПАО Эллипс",
      "Центральная, 7",
      "8(555)6543210"
    ]
  }
]