> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brama.work/llms.txt
> Use this file to discover all available pages before exploring further.

# OLX

> Керування оголошеннями на OLX.ua через AI-агента – Shared App OAuth, read + write через draft→confirm.

<Note>
  **Status: live.** 12 MCP tools – 6 read-only + 6 для створення / редагування / зміни статусу оголошень (5 чернеток через draft→confirm + confirm-tool).
</Note>

## Як це працює

OLX інтеграція – **Shared App** OAuth. Brama тримає **один** OLX-застосунок; тобі не треба реєструвати власний застосунок чи заводити ключі. Ти просто натискаєш Connect, проходиш OLX consent, і агент отримує доступ до твоїх оголошень.

Токени зберігаються **зашифрованими** (ключі поза базою), ізольовано per-tenant. Brama персистить ротовані токени автоматично – повторний consent при звичайній роботі не потрібен.

На відміну від read-only інтеграцій, OLX має **write-tools** – агент може створювати, редагувати, активувати, деактивувати й видаляти оголошення. Кожна зміна йде через **draft→confirm**: агент готує чернетку, ти переглядаєш у картці підтвердження, і **нічого не летить в OLX, доки ти не натиснеш Confirm**.

<Warning>
  Авторизується **той OLX-акаунт, під яким ти залогінений у браузері** в момент Connect. Якщо твої оголошення на іншому акаунті – спершу зайди на [olx.ua](https://www.olx.ua) під потрібним акаунтом (перелогінься), і лише тоді тисни Connect у Brama.
</Warning>

## Підключення

### 1. Connect

[`app.brama.work`](https://app.brama.work) → **Integrations → OLX** → натисни **Connect OLX**.

Тебе перенаправить на OLX consent screen – підтвердиш доступ до своїх оголошень. Brama отримає токени, зашифрує їх і поверне тебе на сторінку інтеграції зі статусом **active**.

<Note>
  Перевір, що на olx.ua ти залогінений саме під тим акаунтом, чиї оголошення хочеш бачити й міняти (див. попередження вище) – OLX авторизує активну сесію браузера.
</Note>

### 2. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI – див. [Connect a client](/connect)):

> Які в мене оголошення на OLX і які з них активні?

Агент викличе `brama_olx_list_my_ads` і поверне список твоїх оголошень зі статусом, назвою, категорією, ціною й датою дії.

## Read tools (live)

Усі 6 read-tools – **read-only**: читають твої оголошення й довідники OLX. Нічого не змінюють.

<Card title="brama_olx_list_my_ads" icon="list">
  Твої власні оголошення зі статусом (наприклад active, limited, outdated, unpaid, moderated, blocked), назвою, id категорії, ціною й датою дії.

  **Параметри:** `limit` *(optional – default 25, max 100)*, `offset` *(optional, paging)*, `status` *(optional – фільтр за одним статусом)*, `category_ids` *(optional – через кому)*.

  Use: "які в мене оголошення?", "покажи заблоковані", "мої неактивні".
</Card>

<Card title="brama_olx_ad_metadata" icon="file-magnifying-glass">
  Повна деталь одного оголошення: статус, назва, опис, категорія, ціна або зарплата, локація, контакт, зображення, атрибути й дати дії.

  **Параметри:** `advert_id` *(required – з `brama_olx_list_my_ads`)*.

  Use: "покажи деталі оголошення X", "що зараз у цьому оголошенні?".
</Card>

<Card title="brama_olx_categories" icon="folder-tree">
  Довідкове дерево категорій OLX – кожна категорія має id, назву, батьківський id, ліміт фото й прапорець "листок".

  **Параметри:** `parent_id` *(optional – прямі підкатегорії; без нього повертає верхній рівень)*.

  Use: "знайди категорію для товару", "покажи підкатегорії X".
</Card>

<Card title="brama_olx_category_suggestion" icon="wand-magic-sparkles">
  Підбір категорій за назвою – кандидати з id та батьківським шляхом, щоб обрати правильний id перед створенням оголошення.

  **Параметри:** `title` *(required – назва оголошення або короткий опис товару, мін. 3 символи)*.

  Use: "в яку категорію постити 'дитячий велосипед'?".
</Card>

<Card title="brama_olx_category_attributes" icon="table-list">
  Схема атрибутів однієї категорії: які поля потрібні оголошенню в цій категорії (наприклад стан, бренд, розмір), які обов'язкові й які дозволені значення. Виклич це **перед** створенням чи редагуванням, щоб знати, які атрибути вказати.

  **Параметри:** `category_id` *(required – з `brama_olx_categories` або `brama_olx_category_suggestion`)*.

  Use: "які поля треба для оголошення в цій категорії?".
</Card>

<Card title="brama_olx_locations" icon="location-dot">
  Довідник локацій OLX – регіони (завжди) і, опційно, сторінка міст з їхнім id регіону та координатами.

  **Параметри:** `include_cities` *(optional – міст тисячі, тому посторінково)*, `offset`, `limit` *(optional – default 100, max 1000)*.

  Use: "знайди id міста для оголошення".
</Card>

## Write tools (live)

Створення, редагування й зміна статусу оголошень ідуть **тільки через картку підтвердження**. Кожен write-tool – це `*_draft`: він готує зміну й показує **інтерактивну картку** (назва, категорія, ціна + Confirm/Cancel). **Нічого не відбувається, доки ти не натиснеш Confirm.** Прямого apply-tool немає навмисно.

<Card title="brama_olx_post_ad_draft" icon="plus">
  Підготувати **нове** оголошення й показати картку підтвердження перед публікацією. Агент спершу збирає оголошення з обов'язкових атрибутів категорії (`brama_olx_category_attributes`).

  **Параметри:** `advert` *(required – повне оголошення як JSON-об'єкт)*.
</Card>

<Card title="brama_olx_edit_ad_draft" icon="pen-to-square">
  Підготувати **оновлення** наявного оголошення й показати картку. Edit **замінює оголошення цілком**, тож щоб змінити одне поле – агент спершу дістає поточне оголошення (`brama_olx_ad_metadata`), міняє потрібне й шле повний об'єкт назад.

  **Параметри:** `advert_id` *(required)*, `advert` *(required – повне оголошення як JSON-об'єкт)*.
</Card>

<Card title="brama_olx_activate_ad_draft" icon="circle-play">
  Підготувати **активацію** оголошення (опублікувати нове, що потребує пакета, або повернути в ефір outdated/деактивоване) і показати картку.

  **Параметри:** `advert_id` *(required)*.
</Card>

<Card title="brama_olx_deactivate_ad_draft" icon="circle-pause">
  Підготувати **деактивацію** (зняти з публікації) активного оголошення і показати картку. Деактивоване оголошення можна активувати знову.

  **Параметри:** `advert_id` *(required)*, `sold` *(optional – true, якщо товар продано)*.
</Card>

<Card title="brama_olx_delete_ad_draft" icon="trash">
  Підготувати **безповоротне видалення** оголошення і показати картку. Видалення незворотне, і оголошення спершу треба деактивувати (`brama_olx_deactivate_ad_draft`).

  **Параметри:** `advert_id` *(required)*.
</Card>

<Card title="brama_olx_confirm_action" icon="circle-check">
  Виконати зміну, яку підготувала чернетка (створення, редагування, активація, деактивація чи видалення). Single-use токен. На хостах, що рендерять картку, цей tool викликається лише кнопкою **Confirm** – не напряму агентом.

  **Параметри:** `confirm_token` *(required)*, `advert` *(required для post/edit; для activate/deactivate/delete не потрібен)*.
</Card>

## Write-безпека

* **Draft→confirm на кожну зміну.** Створення, редагування, активація, деактивація й видалення завжди йдуть через картку підтвердження. Агент лише готує чернетку – **жодна зміна не летить в OLX без твого явного кліку Confirm**. Прямого apply-tool немає.
* **Ліміти надсилання.** Не більше **10 підтверджених дій на годину** і **30 на добу**. Це захищає твій акаунт від випадкового шквалу змін. Перевищиш ліміт – агент скаже почекати, наявні оголошення не постраждають.
* **Видалення в два кроки.** Видалити можна лише деактивоване оголошення, і сам delete проходить окрему картку – випадково стерти активне оголошення не вийде.

<Note>
  **Статус `limited`.** Якщо оголошення має статус `limited` – це означає, що вичерпано **безкоштовний ліміт** оголошень у цій категорії. Щоб опублікувати більше, треба докупити пакет **на боці OLX** (Brama гроші не витрачає й пакети не купує). Купи пакет на olx.ua, тоді проси агента активувати оголошення.
</Note>

## Приклади запитів агенту

* "Які в мене оголошення на OLX і які активні?"
* "Покажи деталі оголошення про диван."
* "В яку категорію постити дитячий велосипед?"
* "Які поля обов'язкові для оголошення в цій категорії?"
* "Створи оголошення: продаю велосипед, 3000 грн, Київ." (агент покаже картку перед публікацією)
* "Онови ціну в оголошенні про диван до 2500 грн."
* "Познач оголошення про телефон як продане й зніми з публікації."
* "Видали старе оголошення про шафу." (агент спершу деактивує, потім покаже картку видалення)

## Troubleshooting

* **"0 оголошень" на активному акаунті** – майже завжди підключено не той OLX-акаунт. Твої оголошення живуть на іншому акаунті. Зайди на [olx.ua](https://www.olx.ua) під потрібним акаунтом і **перепідключи** інтеграцію (Connect) під ним.
* **"unexpected response format"** – тимчасова несумісність відповіді OLX. Це минуще: попроси агента повторити запит за хвилину.
* **Оголошення раптом не читаються / зміни відхиляє** – OLX інвалідує доступ **після 30 днів неактивності**. Просто натисни **Connect** ще раз на сторінці інтеграції – це відновить доступ.

## Безпека

* **Shared App** – Brama тримає один OLX-застосунок; тобі НЕ потрібно реєструвати власний. Твої токени належать тільки тобі.
* Токени зашифровані at rest, ключі поза базою; на диск не пишуться, у пам'яті лише на час запиту; у логи не потрапляють.
* Brama персистить ротовані токени автоматично – повторний consent при звичайній роботі не потрібен.
* Кожен tenant ізольований – твої оголошення недосяжні іншим tenant'ам.
* **Write через draft→confirm** – жодна зміна не застосовується без твого явного підтвердження в картці; ліміти 10/год і 30/добу.

## Питання

Питання? Напиши `viktor@brama.work`.