# 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/uk/agents-key-created.desktop.1600.24d4be81.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-агенти».