Інтеграція Jira API з сайтом: тікети, статуси, вебхуки

Клієнти губляться між формою зворотного зв'язку та статусом заявки — менеджери витрачають у середньому 2–3 години на день на ручне перенесення даних з веб-форми в Jira. У результаті втрачається до 15% заявок, а час реакції збільшується на 40%. Підтримка працює наосліп, а керівництво не бачить реальну картину навантаження. Наші інженери вирішують цю проблему за 3–6 днів під ключ: інтеграція Jira API з вашим сайтом, включаючи створення тікетів, синхронізацію статусів, вебхуки та портал самообслуговування для клієнтів. У результаті — нульова втрата заявок, автоматизація рутини та прозорість кожного кроку.

Як аутентифікуватися в Jira API?

Jira Cloud використовує Basic Auth з API-токеном. Токен створюється в налаштуваннях акаунта — ніколи не використовуйте пароль безпосередньо. Для Jira Server застосовується OAuth або особистий токен (PAT). У прикладі нижче — аутентифікація через Python-бібліотеку jira:

from jira import JIRA

jira = JIRA(
    server='https://your-company.atlassian.net',
    basic_auth=('[email protected]', JIRA_API_TOKEN)  # API token, не пароль
)

API-токен дає доступ лише до необхідних проектів. Зберігайте його в змінних середовища, а не в коді.

Як створити задачу з форми на PHP?

Типовий сценарій — користувач заповнює форму підтримки, і на сервері створюється задача Jira. Використовуємо HTTP-клієнт Laravel для надсилання POST-запиту до /rest/api/3/issue:

class JiraService
{
    public function createIssue(SupportRequest $data): string
    {
        $resp = Http::withBasicAuth(
            config('services.jira.email'),
            config('services.jira.token')
        )->post(config('services.jira.url') . '/rest/api/3/issue', [
            'fields' => [
                'project'     => ['key' => 'SUPPORT'],
                'summary'     => "[Web] {$data->subject}",
                'description' => [
                    'type'    => 'doc',
                    'version' => 1,
                    'content' => [[
                        'type'    => 'paragraph',
                        'content' => [['type' => 'text', 'text' => $data->message]],
                    ]],
                ],
                'issuetype'   => ['name' => 'Support'],
                'priority'    => ['name' => $data->priority ?? 'Medium'],
                'labels'      => ['website', 'customer-request'],
                'customfield_10014' => $data->customer_email,  // Кастомне поле email
            ],
        ]);

        $issueKey = $resp->json('key');  // SUPPORT-123

        // Зберігаємо прив'язку заявки до тікету
        SupportTicket::create([
            'user_id'   => $data->userId,
            'jira_key'  => $issueKey,
            'subject'   => $data->subject,
            'status'    => 'open',
        ]);

        return $issueKey;
    }
}

Зверніть увагу: поле issuetype має відповідати типу задачі в проекті. Кастомні поля (наприклад, email клієнта) передаються за ID — їх потрібно попередньо знайти в налаштуваннях Jira.

Як відобразити статус тікету на сайті?

Після створення задачі клієнт хоче бачити її статус. GET-запит до /rest/api/3/issue/{issueKey} повертає всі необхідні поля:

public function getTicketStatus(string $issueKey): array
{
    $resp = Http::withBasicAuth($email, $token)
        ->get(config('services.jira.url') . "/rest/api/3/issue/{$issueKey}");

    $issue = $resp->json();

    return [
        'key'       => $issue['key'],
        'summary'   => $issue['fields']['summary'],
        'status'    => $issue['fields']['status']['name'],
        'updated'   => $issue['fields']['updated'],
        'comments'  => count($issue['fields']['comment']['comments'] ?? []),
    ];
}

Виводьте цю інформацію в особистому кабінеті. Важливо: кешуйте відповіді на 30–60 секунд, щоб не перевищити ліміти Jira API (зазвичай 5000 запитів на годину).

Як налаштувати вебхуки для синхронізації статусу?

Вебхуки — це push-сповіщення від Jira при зміні задачі. Вони в 100 разів ефективніші, ніж опитування статусу кожні 5 хвилин. У Jira Cloud створіть вебхук з подією jira:issue_updated і вкажіть URL вашого сайту. Обробник на Laravel:

Route::post('/webhooks/jira', function (Request $request) {
    $event    = $request->input('webhookEvent');
    $issue    = $request->input('issue');
    $issueKey = $issue['key'];

    if ($event === 'jira:issue_updated') {
        $newStatus = $issue['fields']['status']['name'];

        SupportTicket::where('jira_key', $issueKey)->update([
            'status'     => $this->mapJiraStatus($newStatus),
            'updated_at' => now(),
        ]);

        // Сповістити клієнта про зміну статусу
        $ticket = SupportTicket::where('jira_key', $issueKey)->first();
        if ($ticket) {
            Mail::to($ticket->user->email)->send(new TicketStatusUpdatedMail($ticket));
        }
    }

    return response('ok');
});

Не забудьте перевірити X-Hub-Signature для безпеки (дивіться документацію Jira webhooks).

Покроковий план інтеграції Jira з сайтом

1. Налаштуйте аутентифікацію: створіть API-токен у Jira Cloud.
2. Реалізуйте ендпоінт для створення тікету з веб-форми (POST /rest/api/3/issue).
3. Збережіть ключ тікету в локальній БД для відстеження.
4. Налаштуйте відображення статусу в особистому кабінеті (GET /rest/api/3/issue/{key}).
5. Створіть вебхук у Jira для push-сповіщень про зміну статусу.
6. Реалізуйте обробник вебхуку на сервері з оновленням статусу та сповіщенням клієнта.
7. Протестуйте весь цикл: створення → зміна статусу → відображення.

Для великих клієнтів ми додатково розгортаємо портал самообслуговування, де можна переглядати історію тікетів і залишати коментарі без входу в Jira. Це знижує навантаження на підтримку на 40%.

Скільки часу займає інтеграція?

Вартість розраховується індивідуально — залежить від складності полів, кількості проектів та необхідності кастомних веб-форм. У середньому, наші клієнти економлять від $3000 до $5000 на місяць після впровадження.

Що входить в роботу?

• Документація по інтеграції (схема запитів, ключі, приклади).
• Вихідний код з коментарями (PHP/Laravel або Python).
• Налаштування вебхуків та тестування на staging.
• Навчання команди підтримки роботі з порталом.
• Гарантія стабільної роботи протягом 30 днів.

Наш досвід: більше 50 успішних інтеграцій Jira з сайтами. Гарантуємо, що система не зламається при пікових навантаженнях. Хочете таку ж автоматизацію? Зв'яжіться з нами — за один день оцінимо ваш проект і запропонуємо архітектуру інтеграції.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.