REST API DI agentams ir jūsų serveriui

Atnaujinta 2026 m. lapkričio 2 d.

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.

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.

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. Jį galite įkelti į Postman, Insomnia ar kodo generatorių.

Node.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.

// 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ė“.

Neradote atsakymo? Parašykite mums