snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/developers/extend/capabilities/apis.mdx

@@ -0,0 +1,147 @@
+---
+title: API
+description: Запрашивайте и изменяйте данные CRM программно с помощью REST или GraphQL.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+Twenty разработан для удобства разработчиков и предлагает мощные API, которые адаптируются к вашей пользовательской модели данных. Мы предоставляем четыре различных типа API, чтобы удовлетворить различные интеграционные потребности.
+
+## Подход, ориентированный на разработчиков
+
+Twenty генерирует API специально для вашей модели данных:
+
+* **Длинные ID не требуются**: используйте названия объектов и полей прямо в конечных точках.
+* **Стандартные и пользовательские объекты обрабатываются одинаково**: ваши пользовательские объекты получают такой же доступ к API, как и встроенные.
+* **Выделенные конечные точки**: каждый объект и поле получают свою собственную конечную точку API.
+* **Пользовательская документация**: генерируется специально для модели данных вашего рабочего пространства.
+
+<Note>
+Персонализированная документация по вашему API доступна в разделе **Настройки → API и вебхуки** после создания ключа API. Поскольку Twenty генерирует API, соответствующие вашей пользовательской модели данных, документация уникальна для вашего рабочего пространства.
+</Note>
+
+## Два типа API
+
+### Основной API
+
+Доступен на `/rest/` или `/graphql/`
+
+Работайте с реальными **записями** (данными):
+
+* Создавайте, читайте, обновляйте и удаляйте People, Companies, Opportunities и т. д.
+* Запрашивайте и фильтруйте данные
+* Управление отношениями записей.
+
+### API метаданных
+
+Доступен на `/rest/metadata/` или `/metadata/`
+
+Управляйте своим **рабочим пространством и моделью данных**:
+
+* Создание, изменение или удаление объектов и полей.
+* Настройка параметров рабочего пространства.
+* Определяйте связи между объектами
+
+## REST против GraphQL
+
+И Core, и Metadata API доступны в форматах REST и GraphQL:
+
+| Формат      | Доступные операции                                                       |
+| ----------- | ------------------------------------------------------------------------ |
+| **REST**    | CRUD, пакетные операции, upsert-операции                                 |
+| **GraphQL** | То же самое + **пакетные upsert-операции**, запросы связей за один вызов |
+
+Выбирайте по своим потребностям — оба формата обращаются к одним и тем же данным.
+
+## Конечные точки API
+
+| Среда                       | Базовый URL               |
+| --------------------------- | ------------------------- |
+| **Облако**                  | `https://api.twenty.com/` |
+| **Самостоятельный хостинг** | `https://{your-domain}/`  |
+
+## Аутентификация
+
+Каждый запрос к API требует ключ API в заголовке:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+### Создать ключ API
+
+1. Перейдите в **Настройки → API и Вебхуки**
+2. Нажмите **+ Создать ключ**
+3. Настроить:
+   * **Имя**: описательное название для ключа
+   * **Дата истечения**: когда истекает срок действия ключа
+4. Нажмите **Сохранить**
+5. **Скопируйте сразу** — ключ показывается только один раз
+
+<VimeoEmbed videoId="928786722" title="Создание ключа API" />
+
+<Warning>
+Ваш ключ API предоставляет доступ к конфиденциальным данным. Не делитесь им с ненадежными сервисами. Если он скомпрометирован, немедленно отключите его и создайте новый.
+</Warning>
+
+### Назначить роль ключу API
+
+Для повышения безопасности назначьте конкретную роль, чтобы ограничить доступ:
+
+1. Перейдите в **Настройки → Участники → Роли**
+2. Нажмите на роль, которую хотите назначить
+3. Откройте вкладку **Назначение**
+4. В разделе **Ключи API** нажмите **+ Назначить ключу API**
+5. Выберите ключ API
+
+Ключ унаследует разрешения этой роли. См. [Разрешения](/l/ru/user-guide/permissions-access/capabilities/permissions) для подробностей.
+
+### Управление API-ключами
+
+**Сгенерировать заново**: Настройки → API и вебхуки → Нажмите ключ → **Сгенерировать заново**
+
+**Удалить**: Настройки → API и вебхуки → Нажмите ключ → **Удалить**
+
+## Песочница API
+
+Тестируйте свои API прямо в браузере с нашей встроенной песочницей — доступной как для **REST**, так и для **GraphQL**.
+
+### Доступ к песочнице
+
+1. Перейдите в **Настройки → API и Вебхуки**
+2. Создайте ключ API (обязательно)
+3. Нажмите на **REST API** или **GraphQL API**, чтобы открыть песочницу
+
+### Что вы получаете
+
+* **Интерактивная документация**: генерируется для вашей конкретной модели данных
+* **Тестирование в реальном времени**: выполняйте реальные вызовы API к вашему рабочему пространству
+* **Обозреватель схемы**: просматривайте доступные объекты, поля и связи
+* **Конструктор запросов**: создавайте запросы с автодополнением
+
+Песочница отражает ваши пользовательские объекты и поля, поэтому документация всегда точна для вашего рабочего пространства.
+
+## Пакетные операции
+
+И REST, и GraphQL поддерживают пакетные операции:
+
+* **Размер пакета**: до 60 записей на запрос.
+* **Операции**: создание, обновление, удаление нескольких записей
+
+**Функции только для GraphQL:**
+
+* **Пакетный upsert**: создание или обновление за один вызов
+* Используйте имена объектов во множественном числе (например, `CreateCompanies` вместо `CreateCompany`)
+
+## Лимиты скорости
+
+Запросы к API ограничиваются для обеспечения стабильности платформы:
+
+| Лимит             | Значение                  |
+| ----------------- | ------------------------- |
+| **Запросы**       | 100 запросов в минуту     |
+| **Размер пакета** | 60 записей за один запрос |
+
+<Tip>
+Используйте пакетные операции, чтобы максимизировать пропускную способность — обрабатывайте до 60 записей за один запрос API вместо выполнения отдельных запросов.
+</Tip>

packages/twenty-docs/l/ru/developers/extend/capabilities/webhooks.mdx

@@ -0,0 +1,112 @@
+---
+title: Вебхуки
+description: Получайте уведомления в реальном времени, когда в вашей CRM происходят события.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+Вебхуки отправляют данные в ваши системы в реальном времени при возникновении событий в Twenty — опрос не требуется. Используйте их, чтобы поддерживать синхронизацию с внешними системами, запускать автоматизации или отправлять оповещения.
+
+## Создать Webhook
+
+1. Перейдите в **Настройки → API и Вебхуки → Вебхуки**
+2. Нажмите **+ Создать вебхук**
+3. Введите URL вашего вебхука (должен быть общедоступным)
+4. Нажмите **Сохранить**
+
+Вебхук активируется сразу и начинает отправлять уведомления.
+
+<VimeoEmbed videoId="928786708" title="Создание вебхука" />
+
+### Управление вебхуками
+
+**Изменить**: Нажмите на вебхук → Обновите URL → **Сохранить**
+
+**Удалить**: Нажмите на вебхук → **Удалить** → Подтвердить
+
+## События
+
+Twenty отправляет вебхуки для следующих типов событий:
+
+| Событие              | Пример                                                     |
+| -------------------- | ---------------------------------------------------------- |
+| **Запись создана**   | `person.created`, `company.created`, `note.created`        |
+| **Запись обновлена** | `person.updated`, `company.updated`, `opportunity.updated` |
+| **Запись удалена**   | `person.deleted`, `company.deleted`                        |
+
+Все типы событий отправляются на URL вашего вебхука. Фильтрация событий может быть добавлена в будущих версиях.
+
+## Формат полезной нагрузки
+
+Каждый вебхук отправляет HTTP POST с телом JSON:
+
+```json
+{
+  "event": "person.created",
+  "data": {
+    "id": "abc12345",
+    "firstName": "Alice",
+    "lastName": "Doe",
+    "email": "alice@example.com",
+    "createdAt": "2025-02-10T15:30:45Z",
+    "createdBy": "user_123"
+  },
+  "timestamp": "2025-02-10T15:30:50Z"
+}
+```
+
+| Поле            | Описание                                              |
+| --------------- | ----------------------------------------------------- |
+| `событие`       | Что произошло (например, `person.created`)            |
+| `данные`        | Полная запись, которая была создана/обновлена/удалена |
+| `метка времени` | Когда произошло событие (UTC)                         |
+
+<Note>
+Ответьте со **статусом HTTP 2xx** (200-299), чтобы подтвердить получение. Ответы вне диапазона 2xx фиксируются как ошибки доставки.
+</Note>
+
+## Валидация вебхуков
+
+Twenty подписывает каждый запрос вебхука для обеспечения безопасности. Проверяйте подписи, чтобы убедиться в подлинности запросов.
+
+### Заголовки
+
+| Заголовок                    | Описание              |
+| ---------------------------- | --------------------- |
+| `X-Twenty-Webhook-Signature` | Подпись HMAC SHA256   |
+| `X-Twenty-Webhook-Timestamp` | Метка времени запроса |
+
+### Шаги проверки
+
+1. Получите метку времени из `X-Twenty-Webhook-Timestamp`
+2. Создайте строку: `{timestamp}:{JSON payload}`
+3. Вычислите HMAC SHA256, используя секрет вашего вебхука
+4. Сравните с `X-Twenty-Webhook-Signature`
+
+### Пример (Node.js)
+
+```javascript
+const crypto = require("crypto");
+
+const timestamp = req.headers["x-twenty-webhook-timestamp"];
+const payload = JSON.stringify(req.body);
+const secret = "your-webhook-secret";
+
+const stringToSign = `${timestamp}:${payload}`;
+const expectedSignature = crypto
+  .createHmac("sha256", secret)
+  .update(stringToSign)
+  .digest("hex");
+
+const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
+```
+
+## Вебхуки vs рабочие процессы
+
+| Метод                                  | Направление | Сценарий использования                                                     |
+| -------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| **Вебхуки**                            | OUT         | Автоматически уведомлять внешние системы о любом изменении записи          |
+| **Рабочий процесс + HTTP-запрос**      | OUT         | Отправлять данные наружу с настраиваемой логикой (фильтры, преобразования) |
+| **Триггер вебхука в рабочем процессе** | IN          | Получать данные в Twenty из внешних систем                                 |
+
+Для получения внешних данных см. [Настройка триггера вебхука](/l/ru/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).