# Локални REST API

> Дозволите другим програмима на овом рачунару да управљају телефоном — упућују позиве и управљају њима, читају контакте, историју и налоге.

AI Softphone има REST API за CTI интеграцију: програм на истом рачунару може да упућује позиве и управља њима, чита контакте, историју позива и SIP налоге и прати позиве у току. Без SDK-а, без посредника у облаку и без слушаоца изложеног мрежи. Захтеви и одговори су JSON, па је довољан `curl` или било који HTTP клијент.

API је **након инсталације искључен**; ништа не слуша док га не укључите. Тада слуша само на loopback сучељу — *малом веб-сучељу које одговара само овом рачунару* — и није доступан из канцеларијске мреже, VPN-а нити са другог рачунара.

Користите API када ваш програм треба податке из телефона или мора да управља позивом. Користите [веб-куке](https://docs.ai-softphone.com/sr/integration/webhooks/index.md) када мора да реагује на позиве док се дешавају, без прозивања. Већина интеграција користи обоје; међусобно су независни.

## Укључивање {#turning-it-on}

Отворите **Подешавања → Повезивање** и идите на **Локално управљање**.

![Подешавања → Повезивање: локално управљање](https://docs.ai-softphone.com/screenshots/macos/sr/17b_settings_integration_scrolled.png)

1. Укључите **Дозволи другим програмима на овом рачунару да управљају телефоном**. Сервер се одмах покреће.
2. Задржите подразумевани **Порт**, `8377`, осим ако га већ користи други програм.
3. По жељи подесите **Жетон**. Након чувања поље приказује *Сачувано — куцајте да замените*.
4. Под **Приступ** изаберите групе које желите да отворите: **Контакти**, **Историја позива**, **Позиви и управљање њима**, **Налози**, **Подешавања**, **Бројачи** (метрике). Искључена група се не филтрира, него се уопште не служи.
5. Испробајте: `curl http://127.0.0.1:8377/accounts`. Ако је одговор JSON, API ради.

Не инсталира се засебна услуга и није потребно поновно покретање. Део програма који то ради може да се искључи у [Модулима](https://docs.ai-softphone.com/sr/application/modules/index.md) (**Повезивање**).

## Сопствена страница API-ја {#the-apis-own-page}

**Отвори сопствену страницу API-ја** отвара `http://127.0.0.1:8377` у прегледачу. Адреса одговара списком свега што служи, на енглеском; адресе које нешто читају су везе које можете да пратите.

![Сопствена страница API-ја, http://127.0.0.1:8377/, отворена у прегледачу](https://docs.ai-softphone.com/screenshots/macos/sr/23_api_page.png)

## Приступ и жетон {#access-and-the-token}

Шта програм сме да ради зависи од тога да ли мења сачуване податке, а не од тога да ли чита:

- **Без жетона** било који програм на рачунару сме да чита све у укљученим групама и да управља позивима: да упути, јави се, прекине, стави на чекање, настави, проследи и шаље DTMF.
- **Са жетоном** у заглављу `Authorization` сме да користи и [крајње тачке које мењају оно што је сачувано](#endpoints-that-need-the-token). Без жетона те крајње тачке се не наводе на сопственој страници API-ја и одговарају са `401`. Ако жетон уопште није подешен, ништа не може да промени сачувано.

Жетон се чува у складишту кључева рачунара, не у датотеци подешавања, и `/settings` га никада не враћа.

:::caution
Без жетона било који програм који ради на овом рачунару може да управља телефоном, укључујући јављање на позиве. На личној радној станици то је обично прихватљиво. На заједничком или управљаном рачунару подесите жетон и поступајте са њим као са било којом другом лозинком. Жетон штити само захтеве који мењају сачуване податке, а не позиве: ако желите да друге програме држите даље од позива, искључите **Позиви и управљање њима** под **Приступ**.
:::

## Крајње тачке {#endpoints}

Основна адреса је `http://127.0.0.1:8377`. Крајње тачке у наставку не захтевају жетон.

| Метод | Путања | Шта ради |
| --- | --- | --- |
| GET | `/metrics` | Бројачи, у формату Prometheus. |
| GET | `/ui` | Списак снимака, као HTML страница. |
| GET | `/ui/recordings/{id}` | Снимак са преписом, као HTML страница. |
| GET | `/ui/recordings/{id}/audio` | Звук за горњу страницу. |
| GET | `/contacts` | Контакти. |
| GET | `/contacts/{id}` | Један контакт. |
| GET | `/history` | Дневник позива, од најновијих. Прихвата `?limit=`, `?missed=true` и `?declined=true`. |
| GET | `/calls` | Позиви у току. |
| POST | `/calls` | Упућује позив: `{"number": "...", "account_id": "..."}`. |
| POST | `/calls/{id}/answer` | Јавља се на позив. |
| POST | `/calls/{id}/hangup` | Прекида позив. |
| POST | `/calls/{id}/hold` | Ставља позив на чекање. |
| POST | `/calls/{id}/resume` | Враћа га са чекања. |
| POST | `/calls/{id}/dtmf` | Шаље тонове: `{"digits": "..."}`. |
| POST | `/calls/{id}/transfer` | Прослеђује позив: `{"target": "..."}`. |
| GET | `/accounts` | SIP налози и стање њихове регистрације. Никада лозинка. |
| GET | `/settings` | Цела конфигурација, без тајни. |
| GET | `/taxonomy` | Категорије, ознаке и упозорења, са њиховим кодовима. |

### Крајње тачке којима треба жетон {#endpoints-that-need-the-token}

Оне мењају оно што је сачувано, па сваки захтев мора да носи жетон у заглављу `Authorization`. Сопствена страница API-ја их приказује само захтеву који га носи.

| Метод | Путања | Шта ради |
| --- | --- | --- |
| POST | `/contacts` | Додаје контакт: `{"name": "...", "number": "...", "account_id": "..."}`; `account_id` није обавезан. |
| PUT | `/contacts/{id}` | Замењује контакт. |
| DELETE | `/contacts/{id}` | Уклања контакт. |
| DELETE | `/history/{id}` | Заборавља један позив из дневника позива. |
| DELETE | `/history` | Заборавља цео дневник позива. То се не може опозвати. |
| PUT | `/accounts/{id}` | Замењује подешавања налога. Лозинка није међу њима. |
| PUT | `/settings` | Замењује подешавања. |

Сваки идентификатор је UUID који додељује телефон: `id` позива долази из `/calls` или из одговора на `POST /calls`, `id` налога из `/accounts`.

Називи поља су у snake_case-у, а завршетак говори о врсти: `_id` је референца на UUID, `_ts` је тренутак у Unix милисекундама (UTC), `_s` је трајање у секундама. Исто важи за веб-куке; само `/settings` има сопствене називе. У REST API-ју те вредности су JSON бројеви, а непознат тренутак је `null`.

## Пример: упућивање позива {#example-placing-a-call}

`POST /calls` упућује одлазни позив. Тело је JSON са `number` који треба позвати и, по жељи, `account_id` налога са ког треба звати:

```bash
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
    "number": "1020",
    "account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
```

Одговор је идентификатор новог позива:

```json
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
```

- `number` је обавезан. Без њега одговор је `400 {"error":"a call needs a number"}` и ништа се не бира.
- Број се на изабраном налогу допуњује као што га допуњује поље за бирање: `1020` се шаље као `sip:1020@pbx.example.com`. `POST /calls/{id}/transfer` допуњује свој `target` на исти начин; циљ који већ има шему или `@` шаље се такав какав јесте.
- `account_id` је необавезан; узмите га из `GET /accounts`. Без њега позив иде са налога изабраног у главном прозору.
- Користите `id` у `/calls/{id}/…`: `hangup`, `hold`, `resume`, `dtmf` и `transfer`. [Веб-куке](https://docs.ai-softphone.com/sr/integration/webhooks/index.md#an-outgoing-call-event-by-event) овог позива носе исти `id`.

### Са веб-странице: клик за позив {#from-a-web-page-click-to-call}

Страница која зове `127.0.0.1` долази до рачунара на ком ради прегледач — истог на ком ради телефон —, па дугме „клик за позив” у CRM-у не треба сопствени сервер:

```javascript
async function dial(number) {
  const r = await fetch("http://127.0.0.1:8377/calls", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ number }),
  });
  if (!r.ok) console.warn("softphone:", (await r.json()).error);
}
```

## Шта садрже одговори {#what-the-answers-contain}

### Позиви у току: `GET /calls` {#calls-in-progress-get-calls}

Сваки позив има свој `id`, `seance_id`, `account_id`, `direction`, `state`, `number`, `name`, `uri`, `dialed`, `muted`, `event_ts`, `callstart_ts` и `callstate_ts`.

- `state` је `dialing`, `ringing-out`, `ringing-in`, `active`, `hold` (на чекање ставио овај телефон), `onhold` (на чекање ставила друга страна), `conference` или `ended`. Када важи више од једног, `conference` има предност над `hold`, а `hold` над `onhold`.
- `muted` каже да ли је микрофон у позиву искључен; искључивање микрофона не мења `state`.
- `seance_id` је разговор: позиви повезани прослеђивањем, консултацијом или конференцијом деле га.
- `event_ts` је тренутак када је одговор настао. Упоредите га са `callstate_ts` да видите колико је дуго позив у свом стању, без ослањања на сопствени сат.

### Налози: `GET /accounts` {#accounts-get-accounts}

Сваки налог има свој `id` (свуда другде `account_id`), своја подешавања — `transport` (`udp`, `tcp` или `tls`), `port`, `registrar`, `outbound_proxy`, `expiry_s` и друга —, да ли је `enabled`, и свој `state` на централи: `registered` док је линија активна. Лозинке никада нису укључене.

### Историја позива: `GET /history` {#call-history-get-history}

Од најновијих, 100 ставки осим ако `?limit=` каже другачије. `?missed=true` враћа само пропуштене позиве, `?declined=true` само позиве које је овај телефон одбио.

| Поље | Значење |
| --- | --- |
| `id` | Сопствени идентификатор ставке историје. То није `id` позива из `/calls` и веб-кука; повезује их `seance_id`. |
| `outcome` | Главна класификација: `answered`, `missed`, `declined` или `failed`. |
| `answered` | `true` или `false`. |
| `duration_s` | `0` за позив који никада није успостављен. |
| `number`, `uri` | Друга страна, као број и као SIP адреса. |
| `name` | Из Контаката ако је број познат, иначе празно. Упарујте по `number`, не по овоме. |
| `dialed` | Биране цифре, за одлазни позив; празно за долазни. |
| `account`, `account_id` | Линија на којој је позив био. |
| `reason` | Како се завршио: `local-hangup`, `remote-hangup`, `cancelled`… |
| `answered_by` | `no` ако се јавио човек; иначе оно што се јавило на позив. |

### Контакти: `GET /contacts` {#contacts-get-contacts}

Сваки контакт има свој `id`, `name`, `number` и линију којој припада, `account_id` и `account`; празан `account` значи да контакт није везан за линију.

### Снимци {#recordings}

Снимци и преписи се не издају као JSON. API их служи као HTML странице, `/ui` и `/ui/recordings/{id}`: повезујте на те странице из свог CRM-а уместо премештања звука. Веза се отвара на рачунару који чува снимак, а звук га никада не напушта.

## Таксономија и подешавања {#taxonomy-and-settings}

Свака ставка `/taxonomy` има сталан `code`, `title` и `description` на језику сучеља, `kind` (`category`, `tag` или `red_flag`) и, за упозорења, `severity`. **Упарујте по `code`, никада по `title`**: наслови долазе на језику на који је телефон подешен. Ставка са `retired: true` задржава се како би се старији позиви и даље разрешавали; новим позивима се више не додељује. Учитајте таксономију једном при покретању да речи телефона пресликате на сопствена поља.

`/settings` враћа конфигурацију осим тајни: звучне уређаје и јачине, приоритет кодека, изглед и језик, покретање, пречице, ниво дијагностике и стање обе интеграције — корисно за алат подршке који мора да провери радну станицу без дељења екрана. `api.disabled` наводи искључене групе приступа, а `webhooks.silenced` искључене догађаје; празни спискови значе да је све укључено. Никада не укључује SIP лозинку, жетон API-ја ни вредност заглавља веб-куке.

## Грешке {#errors}

Свака грешка је JSON са једним кључем `error`, намењена људима, а не рашчлањивању.

| Статус | Тело | Значење |
| --- | --- | --- |
| 404 | `{"error":"no such endpoint"}` | Путања не постоји или је њена група приступа искључена; обоје намерно даје исти одговор. |
| 405 | `{"error":"that endpoint does not take this method"}` | Путања постоји, али не прима ту методу: на пример `POST /settings` уместо `PUT`. |
| 401 | `{"error":"writing needs a token, and none is configured"}` | Крајња тачка која мења сачувано, на телефону где је поље **Жетон** празно. Попуните га у **Локално управљање**. |
| 401 | `{"error":"this endpoint needs the authorization token"}` | Крајња тачка која мења сачувано, без исправног жетона. |
| 404 | `{"error":"no contact with that id"}` | Путања је исправна, идентификатор није. |
| 400 | `{"error":"no call with that id"}` | Позив се завршио или никада није постојао. |
| 400 | `{"error":"a call needs a number"}` | `POST /calls` без броја. Ништа није бирано. |
| 400 | `{"error":"no digits to send"}` | `POST /calls/{id}/dtmf` без цифара. |
| 400 | `{"error":"a transfer needs a target"}` | `POST /calls/{id}/transfer` без циља. |
| 400 | `{"error":"the account this call is on is no longer set up"}` | Налог позива је уклоњен током позива, па циљ не може да се допуни. Централи ништа није послато. |

Одбијени захтеви броје се у `api_requests_refused_total`, па се интеграција која тихо не успева види у метрикама, а не само у вашим сопственим дневницима.

## Метрике {#metrics}

`GET /metrics` враћа сваки бројач телефона, сваки са текстом помоћи. Прикупљајте их Prometheus-ом или их читајте ручно.

| Бројач | Броји |
| --- | --- |
| `calls_incoming_total` | Примљене долазне позиве. |
| `calls_outgoing_total` | Упућене одлазне позиве. |
| `calls_answered_total` | Позиве на које се неко јавио. |
| `calls_missed_total` | Долазне позиве на које се нико није јавио. |
| `calls_declined_total` | Позиве одбијене овде или на другој страни. |
| `calls_failed_total` | Позиве који нису могли да се успоставе. |
| `registrations_succeeded_total` | Успешне SIP регистрације. |
| `registrations_failed_total` | SIP регистрације одбијене или истекле. |
| `webhooks_delivered_total` | Веб-куке које је прималац прихватио. |
| `webhooks_failed_total` | Веб-куке одбијене или неиспоручене. |
| `webhooks_dropped_total` | Веб-куке одбачене јер је ред био пун. |
| `api_requests_total` | Захтеве које је API обрадио. |
| `api_requests_refused_total` | Одбијене захтеве: погрешан жетон, искључена група или непозната путања. |

## Ажурирање старије интеграције {#updating-an-older-integration}

Раније верзије су користиле називе у camelCase-у и кратке идентификаторе. `accountId` је сада `account_id`, `startedAt` је `callstart_ts`, `durationSeconds` је `duration_s`, `answeredBy` је `answered_by`, а поље веб-куке `at` је `event_ts`. Позиви и налози се идентификују само UUID-ом: `runtimeId` и идентификатори као што су `call-3` или `account-2` више се не враћају нити прихватају.

## Када не ради {#when-it-does-not-work}

| Симптом | Шта проверити |
| --- | --- |
| Веза одбијена на `127.0.0.1:8377` | Локално управљање је искључено, телефон не ради или је порт промењен. |
| `404 {"error":"no such endpoint"}` за путању са ове странице | Њена група приступа је искључена. |
| Читање ради, писање се одбија са `401` | Крајњим тачкама које мењају сачуване податке треба жетон у заглављу `Authorization`, а на телефону најпре треба попунити поље **Жетон**. |
| Наслови категорија нису на енглеском | Наслови прате језик сучеља. Упарујте по `code` из `/taxonomy`. |
| Недостају `accountId`, `startedAt` или `at` | Интеграција је писана за раније називе; погледајте горе. |

За проблем са регистрацијом или самим позивом отворите [Дијагностику](https://docs.ai-softphone.com/sr/troubleshooting/diagnostics/index.md).
