Connections Endpoint

This page is also available in English.

Огляд

Новий 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`

integer

required

ID компанії.

string

required

Назва компанії.

string (ISO 8601)

required

Коли компанію було створено.

string (ISO 8601)

required

Коли компанію було востаннє оновлено.

GoogleAdsCustomer[]

required

Підключені акаунти Google Ads. Порожній масив, якщо підключень немає.

Show Поля GoogleAdsCustomer

integer

required

ID акаунту.

string

required

Назва акаунту.

string

required

Наприклад, "USD", "UAH".

string

required

Наприклад, "America/New_York".

string

required

Наприклад, "ENABLED".

boolean

required

Чи це менеджер (MCC) акаунт.

string (ISO 8601)

required

Коли підключено.

string (ISO 8601)

required

Останнє оновлення.

boolean

Завжди true у цій відповіді.

boolean

Завжди false у цій відповіді.

GoogleBusinessLocation[]

required

Підключені GBP локації. Порожній масив, якщо підключень немає.

Show Поля GoogleBusinessLocation

string

required

Google ідентифікатор локації.

string

required

Назва локації (наприклад, назва бізнесу).

string | null

Зовнішній ідентифікатор локації.

string | null

Посилання на локацію в Google Maps.

object | null

Фізична адреса.

Show Поля адреси

string | null

CLDR код регіону (наприклад, "UA", "US").

string | null

BCP-47 код мови.

string | null

Поштовий індекс.

string | null

Область / штат.

string | null

Місто.

string | null

Район.

string[]

Рядки адреси (вулиця тощо).

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

curl -X GET "https://api.cattix.com/api/v1/companies/me/connections" \
  -H "Authorization: Bearer YOUR_TOKEN"

import httpx

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

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

[
  {
    "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": []
  }
]

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

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

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

curl -X GET "https://api.cattix.com/api/v1/companies/me/42/connections" \
  -H "Authorization: Bearer YOUR_TOKEN"

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

{
  "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 локації з окремих ендпоінтів:

Замініть кілька запитів одним

Замініть окремі виклики Google Ads та GBP ендпоінтів на один запит до GET /api/v1/companies/me/connections.

Оновіть модель даних

Відповідь групує підключення по компаніях. Налаштуйте стан UI відповідно:

interface CompanyWithConnections {
  id: number;
  name: string;
  date_added: string;
  date_updated: string;
  google_ads_customers: GoogleAdsCustomer[];
  google_business_locations: GoogleBusinessLocation[];
}

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

Приберіть фільтрацію на клієнті

Бекенд вже фільтрує неактивні / видалені ресурси. Приберіть перевірки is_active / is_deleted на фронтенді.

Спростіть кешування на клієнті (опціонально)

Якщо у вас було клієнтське кешування даних підключень, його можна спростити або прибрати, бо бекенд тепер кешує відповідь.

Getting started

Customization

Writing content

AI tools

Google Ads

Companies

Campaigns

Огляд

Ендпоінти

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

`CompanyWithConnections`

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

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

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

Кешування

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

​Огляд

​Ендпоінти

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

​CompanyWithConnections

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

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

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

​Кешування

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

Огляд

Ендпоінти

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

`CompanyWithConnections`

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

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

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

Кешування

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