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

# Connections Endpoint

> Єдиний ендпоінт для отримання всіх підключень користувача (Google Ads акаунти та Google Business Profile локації), згрупованих по компаніях

<Note>
  This page is also available in [English](/guides/connections-endpoint).
</Note>

## Огляд

Новий **Connections endpoint** дозволяє одним API-запитом отримати всі
підключені сервіси користувача — акаунти Google Ads та локації Google Business
Profile (GBP) — згруповані по компаніях.

**Раніше:** фронтенд мав викликати окремі ендпоінти для Google Ads і GBP
локацій, часто повторюючи запити для кожної компанії (проблема N+1).

**Тепер:** один виклик `GET /api/v1/companies/me/connections` повертає все.

***

## Ендпоінти

| Ендпоінт                                            | Повертає                       | Коли використовувати                                           |
| --------------------------------------------------- | ------------------------------ | -------------------------------------------------------------- |
| `GET /api/v1/companies/me/connections`              | `list[CompanyWithConnections]` | Дашборд / сайдбар — отримати всі підключення по всіх компаніях |
| `GET /api/v1/companies/me/{company_id}/connections` | `CompanyWithConnections`       | Сторінка компанії — підключення конкретної компанії            |

Обидва потребують валідний заголовок `Authorization: Bearer <token>`.

***

## Формат відповіді

Обидва ендпоінти повертають однакову структуру — об'єкт компанії з двома
масивами підключень. Ендпоінт "усі підключення" обгортає це у список.

### `CompanyWithConnections`

<ResponseField name="id" type="integer" required>
  ID компанії.
</ResponseField>

<ResponseField name="name" type="string" required>
  Назва компанії.
</ResponseField>

<ResponseField name="date_added" type="string (ISO 8601)" required>
  Коли компанію було створено.
</ResponseField>

<ResponseField name="date_updated" type="string (ISO 8601)" required>
  Коли компанію було востаннє оновлено.
</ResponseField>

<ResponseField name="google_ads_customers" type="GoogleAdsCustomer[]" required>
  Підключені акаунти Google Ads. Порожній масив, якщо підключень немає.

  <Expandable title="Поля GoogleAdsCustomer">
    <ResponseField name="id" type="integer" required>ID акаунту.</ResponseField>
    <ResponseField name="descriptive_name" type="string" required>Назва акаунту.</ResponseField>
    <ResponseField name="currency_code" type="string" required>Наприклад, `"USD"`, `"UAH"`.</ResponseField>
    <ResponseField name="time_zone" type="string" required>Наприклад, `"America/New_York"`.</ResponseField>
    <ResponseField name="status" type="string" required>Наприклад, `"ENABLED"`.</ResponseField>
    <ResponseField name="manager" type="boolean" required>Чи це менеджер (MCC) акаунт.</ResponseField>
    <ResponseField name="date_added" type="string (ISO 8601)" required>Коли підключено.</ResponseField>
    <ResponseField name="date_updated" type="string (ISO 8601)" required>Останнє оновлення.</ResponseField>
    <ResponseField name="is_active" type="boolean">Завжди `true` у цій відповіді.</ResponseField>
    <ResponseField name="is_deleted" type="boolean">Завжди `false` у цій відповіді.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="google_business_locations" type="GoogleBusinessLocation[]" required>
  Підключені GBP локації. Порожній масив, якщо підключень немає.

  <Expandable title="Поля GoogleBusinessLocation">
    <ResponseField name="id" type="string" required>Google ідентифікатор локації.</ResponseField>
    <ResponseField name="title" type="string" required>Назва локації (наприклад, назва бізнесу).</ResponseField>
    <ResponseField name="store_code" type="string | null">Зовнішній ідентифікатор локації.</ResponseField>
    <ResponseField name="maps_uri" type="string | null">Посилання на локацію в Google Maps.</ResponseField>

    <ResponseField name="storefront_address" type="object | null">
      Фізична адреса.

      <Expandable title="Поля адреси">
        <ResponseField name="region_code" type="string | null">CLDR код регіону (наприклад, `"UA"`, `"US"`).</ResponseField>
        <ResponseField name="language_code" type="string | null">BCP-47 код мови.</ResponseField>
        <ResponseField name="postal_code" type="string | null">Поштовий індекс.</ResponseField>
        <ResponseField name="administrative_area" type="string | null">Область / штат.</ResponseField>
        <ResponseField name="locality" type="string | null">Місто.</ResponseField>
        <ResponseField name="sublocality" type="string | null">Район.</ResponseField>
        <ResponseField name="address_lines" type="string[]">Рядки адреси (вулиця тощо).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Приклад запиту та відповіді

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cattix.com/api/v1/companies/me/connections" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python (httpx) theme={null}
  import httpx

  response = httpx.get(
      "https://api.cattix.com/api/v1/companies/me/connections",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
  )
  data = response.json()
  ```
</CodeGroup>

**Відповідь** (`200 OK`):

```json theme={null}
[
  {
    "id": 1,
    "name": "Моє агентство",
    "date_added": "2025-06-15T10:30:00",
    "date_updated": "2025-12-01T14:22:00",
    "google_ads_customers": [
      {
        "id": 1234567890,
        "descriptive_name": "Магазин клієнта",
        "currency_code": "USD",
        "time_zone": "America/New_York",
        "status": "ENABLED",
        "manager": false,
        "date_added": "2025-07-01T09:00:00",
        "date_updated": "2025-11-20T08:15:00",
        "is_active": true,
        "is_deleted": false
      }
    ],
    "google_business_locations": [
      {
        "id": "locations/abc123",
        "title": "Магазин клієнта — Центр",
        "store_code": "STORE-001",
        "maps_uri": "https://maps.google.com/?cid=123456",
        "storefront_address": {
          "region_code": "US",
          "language_code": "en",
          "postal_code": "10001",
          "administrative_area": "NY",
          "locality": "New York",
          "sublocality": null,
          "address_lines": ["123 Main St"]
        }
      }
    ]
  },
  {
    "id": 2,
    "name": "Сайд-проєкт",
    "date_added": "2025-09-10T12:00:00",
    "date_updated": "2025-09-10T12:00:00",
    "google_ads_customers": [],
    "google_business_locations": []
  }
]
```

<Tip>
  Компанії без підключень все одно присутні у відповіді — їхні масиви
  `google_ads_customers` та `google_business_locations` порожні.
  Це дозволяє показувати "Ще немає підключень" без додаткової логіки.
</Tip>

***

## Ендпоінт для однієї компанії

Щоб отримати підключення конкретної компанії, вкажіть її ID у шляху:

```bash theme={null}
curl -X GET "https://api.cattix.com/api/v1/companies/me/42/connections" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Повертає **один об'єкт** (не масив):

```json theme={null}
{
  "id": 42,
  "name": "Моє агентство",
  "date_added": "2025-06-15T10:30:00",
  "date_updated": "2025-12-01T14:22:00",
  "google_ads_customers": [ ... ],
  "google_business_locations": [ ... ]
}
```

***

## Що фільтрується автоматично

Бекенд автоматично виключає неактивні та видалені ресурси. Вам **не потрібно**
фільтрувати на фронтенді. Виключаються:

| Виключається коли…                | Приклад                            |
| --------------------------------- | ---------------------------------- |
| Компанію м'яко видалено           | Компанію видалив адмін             |
| Членство користувача неактивне    | Користувача прибрали з компанії    |
| Зв'язок підключення неактивний    | Google Ads акаунт було від'єднано  |
| Сам ресурс неактивний / видалений | Google Ads акаунт було призупинено |

***

## Кешування

Відповіді кешуються на бекенді (Redis). Вам **не потрібно** реалізовувати
кешування на фронтенді.

Кеш автоматично інвалідується коли:

* Компанію створено, оновлено або видалено
* Учасника додано або прибрано з компанії
* Google Ads акаунт або GBP локацію підключено / від'єднано

Це означає, що виклик ендпоінту після будь-якої мутації поверне актуальні дані.

***

## Гайд з міграції

Якщо ви зараз отримуєте Google Ads акаунти та GBP локації з окремих ендпоінтів:

<Steps>
  <Step title="Замініть кілька запитів одним">
    Замініть окремі виклики Google Ads та GBP ендпоінтів на один запит до
    `GET /api/v1/companies/me/connections`.
  </Step>

  <Step title="Оновіть модель даних">
    Відповідь групує підключення по компаніях. Налаштуйте стан UI відповідно:

    ```typescript theme={null}
    interface CompanyWithConnections {
      id: number;
      name: string;
      date_added: string;
      date_updated: string;
      google_ads_customers: GoogleAdsCustomer[];
      google_business_locations: GoogleBusinessLocation[];
    }

    // Ендпоінт "усі підключення" повертає:
    type AllConnections = CompanyWithConnections[];
    ```
  </Step>

  <Step title="Приберіть фільтрацію на клієнті">
    Бекенд вже фільтрує неактивні / видалені ресурси. Приберіть перевірки
    `is_active` / `is_deleted` на фронтенді.
  </Step>

  <Step title="Спростіть кешування на клієнті (опціонально)">
    Якщо у вас було клієнтське кешування даних підключень, його можна спростити
    або прибрати, бо бекенд тепер кешує відповідь.
  </Step>
</Steps>