API сущностей

Все бизнес-объекты — заявки, клиенты, задачи и любые кастомные сущности — доступны через единый динамический эндпоинт /api/e/{model}.

{model} — имя таблицы (например, it_requests, crm_clients, project_tasks). Список всех таблиц: GET /api/sys/entities.

Хранение данных: все кастомные поля записываются в JSONB-колонку data. Стандартные поля (id, tenant_id, created_by, updated_by, created_at, updated_at) — отдельные колонки.

GET /api/e/{model} — список

bash

curl "https://app.orbita.example/api/e/it_requests?page=1&per_page=20" \
  -H "Authorization: Bearer <token>"

Для сложных фильтров используйте POST /api/e/{model}/list-server — см. Фильтрация.

GET /api/e/{model}/{id} — одна запись

bash

curl https://app.orbita.example/api/e/it_requests/42 \
  -H "Authorization: Bearer <token>"

json

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Не работает VPN",
    "status": "in_work",
    "priority": "high",
    "requested_by": 5,
    "assignee": 3,
    "category": 2,
    "due_date": "2024-02-15",
    "created_by": 5,
    "created_at": "2024-02-10T09:00:00Z",
    "updated_at": "2024-02-10T11:30:00Z"
  }
}

POST /api/e/{model} — создать запись

http

POST /api/e/it_requests
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Не работает VPN",
  "priority": "high",
  "details": "После обновления Windows VPN перестал подключаться",
  "category": 3
}

Что происходит при создании (по порядку):

Проверка прав: it_requests.create (или роль admin)
Валидация полей по конфигурации SysTable
Запуск хука before_create — скрипты могут изменить $data
Сохранение в БД; created_by, updated_by → ID текущего пользователя
Индексация в Meilisearch (некритично — ошибка логируется, не прерывает)
Запись в журнал аудита (action = 'create')
Запуск хука after_create
Автозапуск BPMN: если ProcessTemplate с is_auto_start = true привязан к этой таблице — создаётся ProcessInstance и запускается движок

json

{ "success": true, "data": { "id": 43, "status": "new", ... } }

Код ответа: 201 Created.

PUT /api/e/{model}/{id} — полное обновление

http

PUT /api/e/it_requests/42
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Не работает VPN",
  "status": "in_work",
  "assignee": 3,
  "priority": "high"
}

Что происходит при обновлении (по порядку):

Проверка прав: it_requests.update
Валидация (поля с required становятся nullable — частичное обновление не штрафуется)
Текущие данные сливаются с переданными: array_merge($currentData, $requestData)
Запуск хука before_update ($data = слитые данные, $old = данные до)
Сохранение слитых данных в data-колонку
Индексация в Meilisearch
Запись в аудит: сохраняется только $changes — список изменённых полей с парами «до / после»
Очистка удалённых файлов (если поле file/image было обнулено)
Запуск хука after_update
BPMN-оценка: BpmnEngine::evaluateEntityUpdate() — проверяет complete_on_field_* у pending-задач

PATCH /api/e/{model}/{id} — частичное обновление

Идентично PUT, но предназначен для изменения нескольких полей без передачи всего объекта.

http

PATCH /api/e/it_requests/42
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "resolved",
  "resolution": "Обновил драйвер сетевого адаптера"
}

DELETE /api/e/{model}/{id} — удалить запись

http

DELETE /api/e/it_requests/42
Authorization: Bearer <token>

Что происходит при удалении (по порядку):

Проверка прав: it_requests.delete
Запуск хука before_delete ($old = текущие данные)
Запись в аудит (action = 'delete')
Удаление из Meilisearch
Очистка связей: удаляются строки из всех pivot-таблиц (M2M), где участвует эта запись
Удаление записи
Очистка файлов
Запуск хука after_delete

Код ответа: 204 No Content.

Типы полей и формат значений

Тип	Пример JSON-значения	Примечание
`text`	`"строка"`
`textarea`	`"многострочный\nтекст"`
`integer`	`42`
`float`	`3.14`
`boolean`	`true` / `false`
`date`	`"2024-02-15"`	ISO 8601 date
`datetime`	`"2024-02-15T10:30:00Z"`	ISO 8601 datetime
`value_list`	`"high"`	slug из списка опций
`state_model`	`"in_work"`	slug статуса; переходы ограничены
`user`	`3`	ID пользователя
`model_list`	`5`	ID связанной записи
`company`	`1`	ID компании (`sys_companies`)
`org_unit`	`2`	ID подразделения
`file`	`"path/to/file.pdf"` или `[...]`
`image`	`"uploads/photo.jpg"`
`point`	`{ "lat": 55.75, "lng": 37.62 }`	гео-координаты

Массовый импорт

http

POST /api/e/it_requests/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "rows": [
    { "name": "Заявка 1", "priority": "low",    "status": "new" },
    { "name": "Заявка 2", "priority": "critical","status": "new" },
    { "name": "Заявка 3", "priority": "medium",  "status": "new" }
  ]
}

Каждая строка проходит валидацию и before_create хук. BPMN-процессы запускаются для каждой записи отдельно.

Связи (M2M)

Получить связанные записи

http

GET /api/sys/related_instances/{relation_id}/{table_name}/{instance_id}
Authorization: Bearer <token>

Привязать записи

http

POST /api/sys/add_related_instances/{relation_id}/{table_position}/{instance_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "ids": [5, 7, 12]
}

table_position — l_table или r_table (позиция текущей таблицы в связи).

Отвязать запись

http

POST /api/sys/relations/unlink/{relation_id}/{table_position}/{right_id}
Authorization: Bearer <token>

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

http

GET /api/sys/relations/all/{sys_table_id}
Authorization: Bearer <token>

Возвращает все SysRelation, в которых участвует таблица.

Валидация и ошибки

Orbita генерирует правила валидации из конфигурации полей:

Тип поля	Правила Laravel
`required: true`	`required`
`text`, `textarea`	`string`
`integer`, `float`	`numeric`
`date`, `datetime`	`date`
`model_list`	`exists:{target_table},id`

Ошибка валидации — 422 Unprocessable Entity:

json

{
  "success": false,
  "message": "Validation error",
  "errors": {
    "name":     ["The name field is required."],
    "category": ["The selected category is invalid."]
  }
}

Исключение из хука before_* (например, при валидации дат):

json

{
  "success": false,
  "message": "Дата начала не может быть позже даты окончания."
}

Структура сущностей (метаданные)

Список всех таблиц:

http

GET /api/sys/entities
Authorization: Bearer <token>

Структура конкретной таблицы:

http

GET /api/sys/entities/name/it_requests
Authorization: Bearer <token>

Ответ содержит table_fields (массив полей с типами, опциями, переходами состояний) и automations (хуки).

История и аудит

История конкретной записи (кто и что менял):

http

GET /api/sys/history/it_requests/42
Authorization: Bearer <token>

Пример ответа:

json

[
  {
    "id": 101,
    "action": "update",
    "user": { "id": 3, "name": "Иван Петров" },
    "changes": {
      "status":   { "old": "assigned", "new": "in_work" },
      "assignee": { "old": null,       "new": 3 }
    },
    "created_at": "2024-02-10T11:30:00Z"
  }
]

API сущностей ​

GET /api/e/{model} — список ​

GET /api/e/{model}/{id} — одна запись ​

POST /api/e/{model} — создать запись ​

PUT /api/e/{model}/{id} — полное обновление ​

PATCH /api/e/{model}/{id} — частичное обновление ​

DELETE /api/e/{model}/{id} — удалить запись ​

Типы полей и формат значений ​

Массовый импорт ​

Связи (M2M) ​

Получить связанные записи ​

Привязать записи ​

Отвязать запись ​

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

Валидация и ошибки ​

Структура сущностей (метаданные) ​

История и аудит ​

API сущностей

GET /api/e/{model} — список

GET /api/e/{model}/{id} — одна запись

POST /api/e/{model} — создать запись

PUT /api/e/{model}/{id} — полное обновление

PATCH /api/e/{model}/{id} — частичное обновление

DELETE /api/e/{model}/{id} — удалить запись

Типы полей и формат значений

Массовый импорт

Связи (M2M)

Получить связанные записи

Привязать записи

Отвязать запись

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

Валидация и ошибки

Структура сущностей (метаданные)

История и аудит