# REST API DI agentams ir jūsų serveriui

> HRC pagalbos REST API su asmeniniu raktu: autentifikacija, { error, data } atsakymai, klaidų kodai, OpenAPI aprašas ir pavyzdžiai curl, Node.js, Python.

Tos pačios operacijos, kurias DI agentas mato per MCP, pasiekiamos ir per REST API. Tinka jūsų serveriui, skriptams ir DI programoms be MCP.

## Autentifikacija

Sukurkite DI agentą ir jo asmeninį raktą skiltyje Nustatymai, DI agentai. Raktas (`hrc_live_...`) parodomas vieną kartą. Kiekvieną kvietimą siųskite su antrašte:

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

Raktas veikia to nario vardu, kuris sukūrė DI agentą, ir tik su DI agento leidimais.

![Sukurto rakto langas](https://hrc.lt/screens/lt/agents-key-created.desktop.1600.0aa350ce.webp)

## Kvietimai

Kiekvienas kvietimas yra `POST https://api.hrc.lt/private/<objektas>/<veiksmas>` su JSON. Į kiekvieną kvietimą, kurio įvestis turi `companyId`, įrašykite savo įmonės ID: jį grąžina `/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":[...]}}
```

## Atsakymas ir klaidos

Kiekvienas atsakymas yra `{ error, data }`: viena pusė visada `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
}
```

| Kodas                       | Būsena | Reikšmė                                                                       |
| --------------------------- | ------ | ----------------------------------------------------------------------------- |
| `NOT_AUTHENTICATED`         | 401    | Nėra rakto, raktas atšauktas ar nebegalioja.                                  |
| `AI_AGENTS_OFF`             | 403    | Įmonėje DI agentų prieiga išjungta.                                           |
| `AI_AGENT_PAUSED`           | 403    | DI agentas ar raktas sustabdytas.                                             |
| `AI_AGENT_NOT_ALLOWED`      | 403    | Srities leidimo nepakanka (`details.area`, `details.needed`).                 |
| `AI_AGENT_SEND_NOT_ALLOWED` | 403    | Nėra leidimo siųsti klientams.                                                |
| `OWNER_ROLE_REQUIRED`       | 403    | Veiksmas tik savininkui.                                                      |
| `COMPANY_NOT_FOUND`         | 404    | Ne jūsų įmonė arba narys nebe įmonėje.                                        |
| `TOO_MANY_REQUESTS`         | 429    | Daugiau nei 120 kvietimų per minutę (`details.retryAfterSec`).                |
| `VALIDATION_ERROR`          | 400    | Bloga įvestis (`details.issues`).                                             |
| `CONFLICT`                  | 409    | Kažkas pakeitė objektą anksčiau už jus: perskaitykite ir bandykite dar kartą. |

Antraštė `x-language: lt` arba `en` keičia klaidų pranešimų kalbą.

## OpenAPI aprašas

Visos operacijos su įvestimi ir atsakymais: [https://api.hrc.lt/agent-api/openapi.json](https://api.hrc.lt/agent-api/openapi.json). Jį galite įkelti į Postman, Insomnia ar kodo generatorių.

## Node.js

```js
// Node.js 18 arba naujesnė
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', {});
// Rodiniai: all, new, open, pending, closed, unassigned, mine, snoozed, spam.
// open yra tik būsena „Aktyvus“; all yra visos būsenos.
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 su 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"]

# Paruoštas atsakymas: komandos narys jį peržiūri ir išsiunčia
hrc("/private/prepared-reply/replace", {
    "companyId": company_id,
    "conversationId": "CONVERSATION_ID",
    "bodyMd": "Hello, the payment works again. Thank you for waiting.",
})

# Užduotis, susieta su pokalbiu
hrc("/private/task/create", {
    "companyId": company_id,
    "requestId": str(uuid.uuid4()),
    "title": "Payment fails after the bank check",
    "conversationIds": ["CONVERSATION_ID"],
})
```

## Patikimi profilio laukai iš jūsų serverio

Reikšmės, nuo kurių kas nors priklauso (planas, balansas, teisės), siųskite iš serverio. Jų šaltinis yra komanda, todėl nei svetainė, nei naršyklė jų pakeisti negali. Reikia srities Pokalbiai ir žinutės su keitimo leidimu.

```js
// Iš jūsų serverio: šios reikšmės patikimos (šaltinis "team");
// svetainė ir naršyklė jų pakeisti negali.
// Naudoja hrc() iš Node.js pavyzdžio.
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'],
});
```

## Ribos ir pakartojimai

120 kvietimų per minutę vienam raktui. Gavę `429`, palaukite `details.retryAfterSec` sekundžių. Kurdami objektus siųskite `requestId` (UUID): pakartotas tas pats kvietimas nesukurs dublikato.

Kiekvienas kvietimas įrašomas į veiksmų žurnalą „Ką DI agentai darė“.