Skip to content

The open alternative to Salesforce, designed for AI.

5.9 KB
Raw Blame
---
title: API
sidebarTitle: Обзор
description: REST и GraphQL API, сгенерированные на основе схемы вашего рабочего пространства.
---

import { PageBanner } from "/snippets/page-banner.mdx"
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

## API с отдельной схемой для каждого тенанта

Для Twenty нет статической документации по API. У каждого рабочего пространства своя схема — когда вы добавляете пользовательский объект (например, `Invoice`), он сразу получает эндпоинты REST и GraphQL, идентичные встроенным объектам, таким как `Company` или `Person`. API генерируется из схемы, поэтому эндпоинты напрямую используют названия ваших объектов и полей — никаких непрозрачных идентификаторов.

Документация по API для вашего рабочего пространства доступна в разделе **Настройки → Разработчики → API** после создания ключа API. Она включает интерактивную песочницу, где вы можете выполнять реальные вызовы к своим данным.

## Два API

**Основное API** — `/rest/` и `/graphql/`

CRUD над записями: Люди, Компании, Сделки, ваши пользовательские объекты. Запросы, фильтрация, переход по связям.

**API метаданных** — `/rest/metadata/` и `/metadata/`

Управление схемой: создание/изменение/удаление объектов, полей и связей. Так вы программно изменяете свою модель данных.

Оба доступны как REST и GraphQL. GraphQL добавляет пакетные upsert-операции и возможность переходить по связям в одном запросе. В обоих случаях используются одни и те же базовые данные.

## Базовые URL-адреса

| Среда                   | Базовый URL               |
| ----------------------- | ------------------------- |
| Облако                  | `https://api.twenty.com/` |
| Самостоятельный хостинг | `https://{your-domain}/`  |

## Аутентификация

```
Authorization: Bearer YOUR_API_KEY
```

Создайте ключ API в **Настройки → Разработчики → API → + Создать ключ**. Сразу скопируйте его — он показывается только один раз. Ключам можно задать область действия для конкретной роли в разделе **Settings → Members → Roles → Assignment tab**, чтобы ограничить их доступ.

<VimeoEmbed videoId="928786722" title="Создание ключа API" />

Для доступа на основе OAuth (внешние приложения, действующие от имени пользователей), см. [OAuth](/ru/developers/extend/oauth).

## Пакетные операции

И REST, и GraphQL поддерживают пакетную обработку до 60 записей за один запрос — создание, обновление или удаление. GraphQL также поддерживает пакетный upsert (создание или обновление за один вызов), используя имена во множественном числе, например `CreateCompanies`.

## Выбор полей (REST)

Конечные точки записей REST принимают параметр запроса `fields`, чтобы возвращать только нужные поля:

```
GET /rest/people?fields=id,name,emails,company
```

* `id` всегда возвращается.
* Составные поля (например, `emails` или `name`) выбираются целиком по имени поля.
* Поле отношения «многие к одному» возвращает свой столбец соединения (например, `companyId`) с `depth=0`. Поля отношения «один ко многим» возвращаются только с `depth=1`. При `depth=1` разворачиваются только поля связей, перечисленные в `fields`.
* Неизвестные поля или поля, которые ваша роль не может читать, возвращают ошибку `400`.

Если `fields` не указан для объекта с более чем 200 доступными для чтения полями, каждая запись возвращает набор из 200 полей по умолчанию: `id`, поля идентификатора метки и изображения, `createdAt`, `updatedAt`, `deletedAt`, `position`, затем стандартные поля перед пользовательскими полями, упорядоченные по имени. Явно передайте `fields`, чтобы прочитать любое поле за пределами этого набора по умолчанию.

## Лимиты скорости

| Лимит         | Значение                  |
| ------------- | ------------------------- |
| Запросы       | 100 запросов в минуту     |
| Размер пакета | 60 записей за один запрос |

<PageBanner illustration="dev-api" />