Astro-компонент для интеграции с Битрикс24

Готовый компонент для интеграции Astro-сайта с CRM Битрикс24. Позволяет легко добавить формы захвата лидов, отправлять данные в CRM и настраивать вебхуки.

Особенности

✅ Простая установка через npm

✅ TypeScript-типы из коробки

✅ Поддержка всех типов полей Битрикс24

✅ Вебхуки и REST API

✅ Документация и примеры

✅ MIT License

Установка

npm install @project-a2/astro-bitrix24-connector

Быстрый старт

1. Создание входящего вебхука

В Битрикс24 перейдите в: CRM → Настройки → Другое → Входящий вебхук

Скопируйте URL вебхука:

https://your-domain.bitrix24.ru/rest/1/abc123def456/

2. Настройка компонента

Создайте файл src/lib/bitrix24.ts:

import { Bitrix24Connector } from '@project-a2/astro-bitrix24-connector';

export const bitrix24 = new Bitrix24Connector({
  webhookUrl: 'https://your-domain.bitrix24.ru/rest/1/abc123def456/',
  defaultParams: {
    sourceId: 'WEB',
    assigneeId: 1 // ID ответственного по умолчанию
  }
});

3. Создание формы

Создайте компонент ContactForm.astro:

---
import { bitrix24 } from '../lib/bitrix24';

let submitted = false;
let error = '';

async function handleSubmit(event) {
  event.preventDefault();
  const formData = new FormData(event.target);

  try {
    await bitrix24.createLead({
      title: formData.get('name'),
      name: formData.get('name'),
      phone: formData.get('phone'),
      email: formData.get('email'),
      comments: formData.get('message')
    });

    submitted = true;
  } catch (e) {
    error = e.message;
  }
}
---

{submitted ? (
  <div class="success">Спасибо! Мы свяжемся с вами.</div>
) : (
  <form onsubmit={handleSubmit}>
    <input type="text" name="name" placeholder="Ваше имя" required />
    <input type="tel" name="phone" placeholder="Телефон" required />
    <input type="email" name="email" placeholder="Email" />
    <textarea name="message" placeholder="Сообщение"></textarea>
    <button type="submit">Отправить</button>
    {error && <div class="error">{error}</div>}
  </form>
)}

API

Bitrix24Connector

new Bitrix24Connector(config: Bitrix24Config)

Конфигурация:

interface Bitrix24Config {
  webhookUrl: string;          // URL входящего вебхука
  defaultParams?: {
    sourceId?: string;         // Источник лида (по умолчанию 'WEB')
    assigneeId?: number;       // ID ответственного
    categoryId?: number;       // ID категории лида
  };
  timeout?: number;            // Таймаут запроса (мс, по умолчанию 10000)
}

Методы

createLead

Создаёт новый лид в Битрикс24.

await bitrix24.createLead({
  title: string;               // Название лида (обязательно)
  name?: string;               // Имя контакта
  lastName?: string;           // Фамилия контакта
  phone?: string;              // Телефон
  email?: string;              // Email
  comments?: string;           // Комментарий
  assigneeId?: number;         // ID ответственного
  sourceId?: string;           // ID источника
  utm?: {                      // UTM-метки
    source?: string;
    medium?: string;
    campaign?: string;
    term?: string;
    content?: string;
  };
});

createContact

Создаёт новый контакт.

await bitrix24.createContact({
  name: string;                // Имя (обязательно)
  lastName?: string;           // Фамилия
  phone?: string;              // Телефон
  email?: string;              // Email
  birthday?: string;           // Дата рождения
});

createDeal

Создаёт новую сделку.

await bitrix24.createDeal({
  title: string;               // Название (обязательно)
  opportunity?: number;        // Сумма сделки
  currencyId?: string;         // Валюта (по умолчанию 'RUB')
  contactId?: number;          // ID контакта
  stageId?: string;            // ID этапа
});

Продвинутые возможности

Обработка UTM-меток

// Получаем UTM из URL
const urlParams = new URLSearchParams(window.location.search);
const utm = {
  source: urlParams.get('utm_source'),
  medium: urlParams.get('utm_medium'),
  campaign: urlParams.get('utm_campaign'),
  term: urlParams.get('utm_term'),
  content: urlParams.get('utm_content')
};

// Передаём при создании лида
await bitrix24.createLead({
  title: 'Лид с сайта',
  utm
});

Кастомные поля

await bitrix24.createLead({
  title: 'Лид с сайта',
  customFields: {
    'UF_CRM_123456': 'Значение кастомного поля'
  }
});

Множественные поля

await bitrix24.createLead({
  title: 'Лид с сайта',
  phone: ['+79001234567', '+79007654321'],
  email: ['test@example.com', 'info@example.com']
});

Демонстрация

Демо-сайт доступен по адресу: https://astro-bitrix24.demo.project-a2.ru

Требования

• Astro 4.x
• Node.js 20+
• Битрикс24 (облако или self-hosted)

Лицензия

MIT License — используйте в коммерческих и личных проектах.

Поддержка

• Документация: https://docs.project-a2.ru/astro-bitrix24
• Issues: https://github.com/project-a2/astro-bitrix24-connector/issues
• Discussions: https://github.com/project-a2/astro-bitrix24-connector/discussions

Roadmap

• Вебхуки
• REST API
• TypeScript типы
• OAuth аутентификация
• Batch запросы
• Server-side рендеринг форм

Контрибьюция

Мы приветствуем контрибьюции! Читайте CONTRIBUTING.md для деталей.

---

Нужна помощь с интеграцией? Напишите нам, мы настроим под ключ.