# Локален REST API

> Позволете на други програми на този компютър да управляват телефона — да провеждат и управляват обаждания, да четат контакти, история и профили.

AI Softphone има REST API за CTI интеграция: програма на същия компютър може да провежда и управлява обаждания, да чете контакти, историята на обажданията и SIP профилите и да следи текущите обаждания. Без SDK, без облачен посредник и без слушател, изложен на мрежата. Заявките и отговорите са JSON, така че `curl` или който и да е HTTP клиент е достатъчен.

API е **изключен след инсталиране**; нищо не слуша, докато не го включите. Тогава той слуша само на интерфейса loopback — *малък уеб интерфейс, който отговаря само на този компютър* — и не може да бъде достигнат от офисната мрежа, през VPN или от друг компютър.

Използвайте API, когато програмата ви се нуждае от данни от телефона или трябва да управлява обаждане. Използвайте [уебкукички](https://docs.ai-softphone.com/bg/integration/webhooks/index.md), когато трябва да реагира на обажданията в момента, в който се случват, без периодични запитвания. Повечето интеграции използват и двете; те са независими една от друга.

## Включване {#turning-it-on}

Отворете **Настройки → Интеграция** и отидете на **Локално управление**.

![Настройки → Интеграция: локално управление](https://docs.ai-softphone.com/screenshots/macos/bg/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/bg/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/bg/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/bg/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/bg/troubleshooting/diagnostics/index.md).
