# REST API для AI-агентов и вашего сервера

> REST API HRC pagalba с личным ключом: аутентификация, ответы { error, data }, коды ошибок, файл OpenAPI и примеры на curl, Node.js и Python.

Операции, которые AI-агент видит через MCP, доступны и через REST API. Это подходит для вашего сервера, скриптов и AI-приложений без MCP.

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

Создайте AI-агента и его личный ключ в разделе «Настройки», «AI-агенты». Ключ (`hrc_live_...`) показывается один раз. Отправляйте каждый вызов с заголовком:

```text
Authorization: Bearer hrc_live_...
```

Ключ действует от имени участника, создавшего AI-агента, и только с разрешениями AI-агента.

![Окно созданного ключа](https://hrc.lt/screens/ru/agents-key-created.desktop.1600.8eac972a.webp)

## Вызовы

Каждый вызов это `POST https://api.hrc.lt/private/<объект>/<действие>` с JSON. В каждый вызов, у которого есть `companyId`, вписывайте ID своей компании: его возвращает `/private/ai-agent-self/get`.

```sh
curl -s https://api.hrc.lt/private/ai-agent-self/get \
  -H "Authorization: Bearer $HRC_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# {"error":null,"data":{"companyId":"...","companyName":"...",
#   "areas":{...},"tools":[...]}}
```

## Ответы и ошибки

Каждый ответ это `{ error, data }`: одна сторона всегда `null`.

```json
{
  "error": {
    "code": "AI_AGENT_NOT_ALLOWED",
    "message": "This AI agent is not allowed to do this. ...",
    "details": { "area": "kb", "needed": "write" }
  },
  "data": null
}
```

| Код                         | Статус | Значение                                                            |
| --------------------------- | ------ | ------------------------------------------------------------------- |
| `NOT_AUTHENTICATED`         | 401    | Нет ключа, ключ отозван или истёк.                                  |
| `AI_AGENTS_OFF`             | 403    | Доступ AI-агентов в компании выключен.                              |
| `AI_AGENT_PAUSED`           | 403    | AI-агент или ключ приостановлен.                                    |
| `AI_AGENT_NOT_ALLOWED`      | 403    | Недостаточно разрешений области (`details.area`, `details.needed`). |
| `AI_AGENT_SEND_NOT_ALLOWED` | 403    | Нет разрешения отправлять клиентам.                                 |
| `OWNER_ROLE_REQUIRED`       | 403    | Действие только для владельцев.                                     |
| `COMPANY_NOT_FOUND`         | 404    | Не ваша компания, или участник её покинул.                          |
| `TOO_MANY_REQUESTS`         | 429    | Больше 120 вызовов в минуту (`details.retryAfterSec`).              |
| `VALIDATION_ERROR`          | 400    | Неверные входные данные (`details.issues`).                         |
| `CONFLICT`                  | 409    | Кто-то изменил объект раньше вас: прочитайте его снова и повторите. |

Заголовок `x-language: lt` или `en` меняет язык сообщений об ошибках.

## Файл OpenAPI

Все операции с входными данными и ответами: [https://api.hrc.lt/agent-api/openapi.json](https://api.hrc.lt/agent-api/openapi.json). Его можно загрузить в Postman, Insomnia или генератор кода.

## Node.js

```js
// Node.js 18 или новее
const API = 'https://api.hrc.lt';

async function hrc(path, body) {
  const response = await fetch(API + path, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.HRC_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  const { error, data } = await response.json();
  if (error) throw new Error(error.code + ': ' + error.message);
  return data;
}

const me = await hrc('/private/ai-agent-self/get', {});
// Списки: all, new, open, pending, closed, unassigned, mine, snoozed, spam.
// open означает только статус «Активный»; all означает все статусы.
const list = await hrc('/private/conversation/list', {
  companyId: me.companyId,
  view: 'all',
  limit: 20,
});
for (const item of list.items) {
  console.log(item.ref, item.subject, item.contact.name);
}
```

## Python

```python
# Python 3 с requests
import os
import uuid

import requests

API = "https://api.hrc.lt"
HEADERS = {"Authorization": "Bearer " + os.environ["HRC_KEY"]}

def hrc(path, body):
    response = requests.post(
        API + path, json=body, headers=HEADERS, timeout=30
    )
    answer = response.json()
    if answer["error"]:
        error = answer["error"]
        raise RuntimeError(error["code"] + ": " + error["message"])
    return answer["data"]

me = hrc("/private/ai-agent-self/get", {})
company_id = me["companyId"]

# Подготовленный ответ: участник проверяет его и отправляет
hrc("/private/prepared-reply/replace", {
    "companyId": company_id,
    "conversationId": "CONVERSATION_ID",
    "bodyMd": "Hello, the payment works again. Thank you for waiting.",
})

# Задача, связанная с диалогом
hrc("/private/task/create", {
    "companyId": company_id,
    "requestId": str(uuid.uuid4()),
    "title": "Payment fails after the bank check",
    "conversationIds": ["CONVERSATION_ID"],
})
```

## Надёжные поля профиля с вашего сервера

Значения, от которых что-то зависит (тариф, баланс, права), отправляйте с сервера. Их источник команда, поэтому ни ваш сайт, ни браузер не могут их изменить. Нужна область «Диалоги и сообщения» с правом изменения.

```js
// С вашего сервера: эти значения надёжные (источник "team");
// сайт и браузер не могут их изменить.
// Использует hrc() из примера Node.js.
await hrc('/private/contact/set-profile', {
  companyId: me.companyId,
  contactId: 'CONTACT_ID',
  company: { name: 'Acme', plan: 'Enterprise' },
  set: [
    { key: 'plan', type: 'string', value: 'enterprise' },
    { key: 'seats', type: 'number', value: 40 },
    { key: 'renews_at', type: 'date', value: '2027-01-31' },
  ],
  unset: ['trial_ends_at'],
  addTags: ['key-account'],
});
```

## Ограничения и повторы

120 вызовов в минуту на ключ. Получив `429`, подождите `details.retryAfterSec` секунд. При создании объектов отправляйте `requestId` (UUID): повтор того же вызова не создаст дубликат.

Каждый вызов записывается в журнал «Что делали AI-агенты».