API патоказ за програмери.

01 · Quickstart

Од идеја до прв успешен повик

Сите команди се испраќаат како UTF-8 JSON преку HTTPS. За секое барање креирајте нови идентификатори и краток рок на важност.

02 · Contract

Еден envelope за секоја команда

Структурата е верзионирана и обезбедува следливост меѓу апликации, клиенти и разговори. Полето data секогаш е JSON object.

{
  "schemaVersion": 1,
  "messageId": "<new-uuid>",
  "authentication": {
    "username": "<username>",
    "password": "<password>"
  },
  "client": {
    "appId": "idiot.mk",
    "appVersion": "1.0.0",
    "clientSessionId": "<session-uuid>"
  },
  "conversation": {
    "id": "<conversation-uuid>",
    "turn": 1
  },
  "operation": "system.ping",
  "sentAtUtc": "<current-utc-time>",
  "expiresAtUtc": "<short-future-utc-time>",
  "data": {}
}

03 · Operations

Достапни функционалности

Еден contract ги покрива автентикацијата, Finmath и root операциите, Обврски, јавниот feed, објавувањето, гласањето, коментарите, пријавите и администраторската модерација.

// request.data
{}

// response.data
{ "text": "pong" }

{
  "userId": 123,
  "username": "developer",
  "email": "dev@example.com",
  "confirmed": true,
  "emailDelivery": "not-required"
}

04 · user.register

Регистрација и автентикација

Заштитените операции содржат username и password; `coffeemath.license.request` и точното `mk.xman` зачувување фирма се документирани исклучоци. Нема access/refresh токени или серверски сесии; заштитените операции ги проверуваат credentials преку Users кешот, освен admin барањата од root-manager кои се проверуваат во 00_x.usrs.

05 · Finmath 3

Најава и регистрација на фирма за Finmath 3

Клиентот користи appId finmath-3. По најавата, response.data.finmath го содржи корисничкиот профил и сите достапни фирми; клиентот не се поврзува директно на MySQL.

{
  "bookkeepingConnectionId": 321,
  "password": "user-password",
  "shortName": "firma_2026",
  "wholeName": "Фирма ДООЕЛ Скопје",
  "address": "Партизанска",
  "number": "10",
  "city": "Скопје",
  "country": "Македонија",
  "taxNumber": "MK1234567",
  "pid": "1234567",
  "taxObligated": true,
  "planType": 1,
  "accountantPlan": 1,
  "kontenPlanSource": 1,
  "sourceType": 1
}

06 · Reference

Целосна практична референца

Табелите подолу се договорот што треба да го следи клиентот: точен appId, дали credentials само мора да постојат или и се проверуваат, обликот на data и главниот резултат. Сите data вредности се JSON objects.

Поддржани клиенти и избор на база

Систем, корисници и каталог

Finmath 3

Поддржани root.data Operation_Type вредности

Almanac · училишен веб-клиент и дозволени операции

Almanac · Google најава, поврзување профили и серверска проверка — потребна е Google Cloud конфигурација.

Обврски · appId: "obvrski"

Feed, содржина и администрација

Кај анонимна објава серверот го зачувува вистинскиот автор, но post.list и post.get враќаат само author { displayName: "Анонимен корисник", username: null, profilePicture: null }. Само admin.post.pending го враќа вистинскиот author со userId.

07 · Responses

Одговор што може сигурно да се следи

Успешен одговор има status completed и error null. Одбиено барање има status rejected, data null и структуриран error. Кај MySQL грешка се враќаат бројот, SQL state, конкретната порака и безбедна конекциска дијагностика без лозинката.

08 · Examples

Повик што можете веднаш да го приспособите

Примерот автоматски создава свежи UUID вредности и рок од пет минути, за да не копирате истечено барање.

const now = new Date();
const payload = {
  schemaVersion: 1,
  messageId: crypto.randomUUID(),
  authentication: { username: "<username>", password: "<password>" },
  client: {
    appId: "idiot.mk",
    appVersion: "1.0.0",
    clientSessionId: crypto.randomUUID()
  },
  conversation: { id: crypto.randomUUID(), turn: 1 },
  operation: "system.ping",
  sentAtUtc: now.toISOString(),
  expiresAtUtc: new Date(now.getTime() + 5 * 60_000).toISOString(),
  data: {}
};

const response = await fetch("https://vps.xnet.mk:50443/api/commands", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
  signal: AbortSignal.timeout(15_000)
});

const result = await response.json();
if (!response.ok || result.status !== "completed") {
  throw new Error(result.error?.code ?? `HTTP ${response.status}`);
}

09 · Checklist

Правила за стабилна интеграција

Овие правила треба да бидат дел од секоја клиентска имплементација, без оглед на програмскиот јазик.

Magmath 6 — XNet најава и сопствен профил

Клиентот magmath-6 е активен на XNet API. Поддржани се user.login, user.me, user.register, user.update, user.profile-picture.update и постојните change.request.* операции.

Секое барање содржи проверени authentication.username/password. Профилните операции го менуваат само најавениот корисник и го враќаат целиот освежен профил, вклучувајќи profilePicture. Business database операции сè уште не се отворени за овој клиент.

Magmath 6 договор, request полиња и production verification

domIO — домови, уреди и корисници

Точниот идентификатор client.appId: "domIO" е активен на XNet API v1 преку POST https://vps.xnet.mk:50443/api/commands.

На продукцискиот Listener се активни user.register, user.login, user.me и domio.* за каталогот. Домови, катови, простории и уреди може да се бришат со проверка на дозволи. Секое барање повторно ги проверува username/password. За физичкиот уред е потребен канал со потврда пред команда да може да успее.

domIO полиња, v1 envelope и примери за одговори

deldaste.com — јавен каталог на третмани

POST https://vps.xnet.mk:50443/api/commands · client.appId: "deldaste.com" · operation: "catalog.treatment.list"

Ажурирано 08.10.2026: Listener 1.4.2 ја поправа валидацијата на дозволените data полиња за јавните барања без authentication.

Операцијата е јавна и само за читање: нема authentication, корисничка најава, лозинка или session token. Филтерот gender е female или male; резултатот ги вклучува и третманите both. Се враќаат само активни третмани од активни категории, со цени, времетраење и серверскиот редослед.

Резервациите остануваат автентицирани, а административните промени и понатаму бараат Kiki Manager/admin дозвола.

Точен v1 envelope, полиња, JSON одговор, пагинација и грешки

Roomio — тарифници и серверски цени

room.rates.list · room.rates.save · room.rates.quote · room.reservation.request-status

Ажурирано 09.10.2026: availability batch quotes почнуваат по затворање на inventory reader-от. Кај резервација само првото лице мора да има име и презиме; придружните guest slots може да останат празни, но ги задржуваат ID, типот и позицијата.

Цените се пресметуваат на серверот по ноќ, со стандардни и сезонски тарифи, дополнителни легла, краткотрајни понуди и траен snapshot во резервацијата. Истиот договор важи за онлајн и LAN/offline Listener.

Точен договор, правила, дозволи, идемпотентност и грешки

ЗА СИТЕ АГЕНТИ · СИТЕ ПРОЕКТИ

Агенти: барањата за промени во API поднесувајте ги тука

Оваа главна страница е заедничката почетна точка за агентите од сите проекти. Ако ви недостига операција, добивате API грешка или ви треба промена во договорот, поднесете барање во заедничкиот ред на XNet.

1. Прочитајте го упатството преку линкот подолу. Во барањето наведете го сопствениот client.appId, проектот, точните операции, грешката и очекуваниот резултат.
2. Поднесете со change.request.submit на POST https://vps.xnet.mk:50443/api/commands, со обезбедените XNet username/password. Зачувајте го добиениот requestId.
3. На сопственикот испратете само „Поднесено барање #ID — наслов“. Целиот опис останува во редот и се разгледува со Codex. Следете ја одлуката и резултатот со change.request.get; сопствените барања се достапни со change.request.list.

Поднесувањето не е одобрување. Сопственикот одлучува кои барања ќе се обработуваат; агентите не одобруваат сопствени барања.

Отвори упатство за поднесување барање →

Целосен договор и JSON пример во Markdown за агенти

10 · Codex bridge

Безбеден мост со теренски комуникатори

Теренските комуникатори одржуваат TLS WebSocket конекција и се докажуваат со сопствен ECDSA P-256 клуч и server challenge. Приватниот клуч останува DPAPI-заштитен на теренскиот компјутер; нема заеднички клуч, XNet корисник или лозинка.

Roomio — персонал и работни позиции

26 работни позиции во 9 оддели, преведени на 13 јазици, дефинирани и кеширани во Listener за сите хотели. Хотелска листа на вработени, регистрација во kesh.users и повеќе позиции по вработен, без доделување дозволи.

room.positions.list · room.personnel.list · room.personnel.register · room.personnel.positions

Полиња, одговори, пристап, идемпотентност и грешки