Конектори

Підключайте свій застосунок до сторонніх сервісів, як-от Slack, Resend та ElevenLabs. Облікові дані зашифровані, а дії попередньо автентифіковані.

Конектори дають змогу інтегрувати зовнішні сервіси у свій застосунок без необхідності вручну керувати API-ключами в коді. Ти налаштовуєш з’єднання один раз, прив’язуєш його до проєкту та викликаєш готові дії зі свого застосунку. Облікові дані шифруються в стані спокою та ніколи не потрапляють до frontend-коду.

Доступні конектори

Конектор	Категорія	Тип автентифікації	Що робить
Resend	Комунікації	API-ключ	Надсилає транзакційні листи, масові розсилки, виводить список верифікованих доменів
Slack	Комунікації	OAuth	Публікує повідомлення, виводить список каналів і користувачів, реагує на повідомлення, читає треди
ElevenLabs	ШІ	API-ключ	Перетворення тексту на мовлення, список доступних голосів, генерація звукових ефектів

Нові конектори додаються регулярно.

Як працюють конектори

1. Ти створюєш з’єднання — вводиш облікові дані (API-ключ або входиш через OAuth)
2. Прив’язуєш з’єднання до проєкту — це надає проєкту доступ до облікових даних
3. Застосунок викликає дії — запит іде через Proyecta Cloud, який додає облікові дані на стороні сервера

Код застосунку ніколи не має доступу до «сирого» API-ключа або OAuth-токена. Система конекторів самостійно обробляє автентифікацію, обмеження запитів і ведення журналу аудиту.

Налаштування конектора

1. Відкрий свій проєкт у builder
2. Перейди до Settings > Connectors
3. Вибери конектор з каталогу (наприклад, Resend)
4. Введи облікові дані:
   • Конектори з API-ключем (Resend, ElevenLabs): встав свій секретний ключ
   • OAuth-конектори (Slack): увійди та надай доступ
5. Дай з’єднанню назву (наприклад, «Production Resend»)
6. З’єднання перевіряється автоматично та позначається Active, якщо воно дійсне

Читання через конектор із застосунку

Твій застосунок може читати сторонній API безпосередньо з браузера, і API-ключ при цьому ніколи не потрапляє до бандлу. Обліковий запис залишається зашифрованим на платформі; застосунок лише вказує конектор, дію та типізовані вхідні дані, а виклик за нього робить платформа.

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

Варто знати про два обмеження — вони навмисні:

• Лише читання. Доступні тільки ті дії, які платформа позначила як безпечні для браузера; решта повертає 403. Записи (публікація в Slack, надсилання листів, списання коштів з картки) з браузера недоступні взагалі.
• Не можна передати URL або хост. Для загального конектора http-read вхідні дані — це { endpointKey, params }, а URL за endpointKey налаштовуєш ти, власник застосунку, а не код застосунку. Відповіді кешуються на сервері та обмежуються за частотою, адже сторонні ключі мають квоти.

404 означає, що власник ще не підключив цей конектор — саме цей випадок варто обробити в інтерфейсі.

Дай ШІ підключити все за тебе

Не обов’язково писати код конекторів вручну. Builder на основі ШІ знає, які конектори прив’язані до твого проєкту, і може згенерувати інтеграцію за тебе:

• "Send a welcome email when users sign up" — використовує конектор Resend
• "Post a Slack message when a new order comes in" — використовує конектор Slack
• "Play audio narration on the article page" — використовує конектор ElevenLabs

Довідник дій конекторів

Resend (connectorId: 'resend')

Дія	Побічні ефекти	Опис
sendEmail	запис	Надсилає один транзакційний лист
sendBatch	запис	Надсилає кілька листів одночасно
listDomains	читання	Виводить список верифікованих доменів-відправників

Slack (connectorId: 'slack')

Дія	Побічні ефекти	Опис
postMessage	запис	Публікує повідомлення в канал
listChannels	читання	Виводить список каналів у воркспейсі
listUsers	читання	Виводить список учасників воркспейсу
reactToMessage	запис	Додає реакцію у вигляді емодзі
getThread	читання	Отримує відповіді в треді

ElevenLabs (connectorId: 'eleven-labs')

Дія	Побічні ефекти	Опис
textToSpeech	запис	Перетворює текст на аудіо-мовлення
listVoices	читання	Виводить список доступних голосів
generateSoundEffect	запис	Генерує звуковий ефект за допомогою ШІ

Статуси з’єднань

Статус	Значення
Active	Облікові дані дійсні, з’єднання готове до використання
Broken	Термін дії облікових даних минув або їх було відкликано — оновіть їх для відновлення

Безпека

• Облікові дані шифруються за алгоритмом AES-256-GCM у стані спокою
• Дії обмежені до 1 000 запитів на хвилину на конектор на проєкт
• Кожен виклик дії фіксується в журналі аудиту (з’єднання, дія, тривалість, статус)
• З’єднання поширюються на весь воркспейс

Часті запитання

Чи можна використовувати одне й те саме з’єднання в кількох проєктах?

Так. Створи з’єднання один раз і прив’яжи його до будь-якої кількості проєктів у межах одного воркспейсу.

Що станеться, якщо мій API-ключ вийде з терміну дії або буде відкликаний?

Статус з’єднання зміниться на Broken. Оновіть облікові дані в Settings > Connectors, щоб відновити його.

Чи можна викликати дії конекторів з frontend?

Твій застосунок ніколи не тримає облікові дані. Безпечні для браузера дії читання проксіюються через Proyecta Cloud, який додає облікові дані на стороні сервера, тож ключ ніколи не потрапляє до бандлу. Дії запису з браузера недоступні взагалі.

Чи можна додати власні конектори?

Поки що ні. Визначення власних конекторів є у планах розробки.

Незабаром

• Нові конектори (Google, Twilio, SendGrid та інші)
• Визначення власних конекторів — підключай свій API
• Прийом вебхуків для вхідних подій від підключених сервісів
• OAuth gateway — токени залишаються на стороні сервера навіть для потоків, ініційованих клієнтом