Astrum Agency

Документация

Руководство пользователя: Заявки с сайта

Обзор приложения

Заявки с сайта — это приложение для автоматического приема и обработки заказов из внешних источников с последующей интеграцией в систему Битрикс24. Приложение позволяет создавать контакты, сделки и лиды в Битрикс24 на основе данных, полученных через API.

Основные возможности

  • 🔐 Безопасная аутентификация через API ключи
  • 📝 Создание заказов через REST API
  • 🔄 Автоматическая обработка заказов в фоновом режиме
  • 📊 Веб-интерфейс для управления заказами
  • 📈 Статистика по обработанным заказам
  • 🔗 Интеграция с Битрикс24 для синхронизации данных

Начало работы

Регистрация приложения в Битрикс24

Установка приложения - Перейдите в админ-панель вашего Битрикс24 - Найдите приложение "Заявки с сайта" в маркетплейсе - Нажмите "Установить"

Авторизация - После установки приложение автоматически создаст учетную запись - Вы получите уникальный API ключ для работы с системой

Доступ к панели управления - Откройте приложение в Битрикс24 - Вы увидите панель управления с настройками и статистикой

Работа с API

Аутентификация

Все API запросы требуют аутентификации через заголовок X-API-Key:

X-API-Key: ваш_api_ключ

Создание заказа

Endpoint: POST https://app-5.astrum.agency/api/order

Заголовки:

Accept: application/json
Content-Type: application/json
X-API-Key: ваш_api_ключ

Пример запроса:

{
  "assigned_default": 1,
  "contact_behavior": "SELECT_EXISTING",
  "entity_behavior": "ADD_TO_EXISTING",
  "contact": {
    "name": "Иван Иванов",
    "phone": "+79991234567",
    "email": "ivan@example.com"
  },
  "deal": {
    "title": "Заявка с сайта",
    "comments": "Клиент заинтересован в товаре",
    "utm_source": "google",
    "utm_medium": "cpc",
    "products": [
      {
        "product_name": "Товар A",
        "price": 1000,
        "quantity": 1
      }
    ]
  }
}

Параметры запроса

Основные параметры

assigned_default (обязательно) — ID ответственного сотрудника по умолчанию - contact_behavior (обязательно) — логика работы с контактами: - CREATE_ANYWAY — всегда создавать новый контакт - SELECT_EXISTING — искать существующий по телефону/email, создавать если не найден entity_behavior (обязательно) — логика работы с сущностями: - CREATE_ANYWAY — всегда создавать новую сделку/лид - IGNORE_EXISTING — игнорировать если найдена активная сущность - ADD_TO_EXISTING — добавлять к существующей активной сущности

Контакт (contact)

  • name (обязательно) — имя контакта
  • phone — телефон (строка или массив объектов с value и value_type)
  • email — email (строка или массив объектов с value и value_type)
  • assigned_by_id — ID ответственного за контакт

Сущность (deal/lead)

  • title (обязательно) — название сделки/лида
  • assigned_by_id — ID ответственного
  • contact_id — ID контакта (заполняется автоматически)
  • source_id — источник
  • comments — комментарии
  • utm_(source,medium,campaign,content,term) — UTM метки для аналитики
  • fields — дополнительные поля Битрикс24
  • products — товары/позиции

Товары (products)

  • product_name (обязательно) — название товара
  • price (обязательно) — цена
  • quantity (обязательно) — количество
  • product_id — ID товара в Битрикс24 (если есть)

Веб-интерфейс

Панель управления

После входа в приложение вы увидите панель управления с двумя основными разделами:

1. Настройки

  • API Ключ — ваш уникальный ключ для работы с API
  • Статистика — общее количество заказов и обработанных заказов
  • Интерактивная документация — встроенная документация API
  • Примеры запросов — готовые примеры для интеграции

2. Заявки

  • Список заказов — таблица со всеми заказами
  • Поиск и фильтрация — поиск по клиентам и фильтр по статусам
  • Пагинация — навигация по страницам
  • Экспорт — выгрузка данных в CSV

Статусы заказов

  • pending — ожидает обработки
  • processing — в процессе обработки
  • completed — успешно обработан
  • failed — ошибка обработки

Интеграция с внешними системами

Примеры интеграции

JavaScript (браузер)

const apiKey = 'ваш_api_ключ';
const apiUrl = 'https://app-5.astrum.agency/api/order';

async function createOrder(orderData) {
  try {
    const response = await fetch(apiUrl, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify(orderData)
    });

    if (response.ok) {
      const result = await response.json();
      console.log('Заказ создан:', result);
      return result;
    } else {
      throw new Error('Ошибка создания заказа');
    }
  } catch (error) {
    console.error('Ошибка:', error);
  }
}

// Пример использования
const orderData = {
  assigned_default: 1,
  contact_behavior: "SELECT_EXISTING",
  entity_behavior: "ADD_TO_EXISTING",
  contact: {
    name: "Иван Иванов",
    phone: "+79991234567",
    email: "ivan@example.com"
  },
  deal: {
    title: "Заявка с сайта",
    comments: "Клиент заинтересован в товаре"
  }
};

createOrder(orderData);

PHP

<?php
$apiKey = 'ваш_api_ключ';
$apiUrl = 'https://app-5.astrum.agency/api/order';

$orderData = [
    'assigned_default' => 1,
    'contact_behavior' => 'SELECT_EXISTING',
    'entity_behavior' => 'ADD_TO_EXISTING',
    'contact' => [
        'name' => 'Иван Иванов',
        'phone' => '+79991234567',
        'email' => 'ivan@example.com'
    ],
    'deal' => [
        'title' => 'Заявка с сайта',
        'comments' => 'Клиент заинтересован в товаре'
    ]
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($orderData));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    echo "Заказ создан: " . $result['id'];
} else {
    echo "Ошибка создания заказа";
}
?>

Python

import requests
import json

api_key = 'ваш_api_ключ'
api_url = 'https://app-5.astrum.agency/api/order'

order_data = {
    'assigned_default': 1,
    'contact_behavior': 'SELECT_EXISTING',
    'entity_behavior': 'ADD_TO_EXISTING',
    'contact': {
        'name': 'Иван Иванов',
        'phone': '+79991234567',
        'email': 'ivan@example.com'
    },
    'deal': {
        'title': 'Заявка с сайта',
        'comments': 'Клиент заинтересован в товаре'
    }
}

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-API-Key': api_key
}

try:
    response = requests.post(api_url, json=order_data, headers=headers)
    response.raise_for_status()

    result = response.json()
    print(f"Заказ создан: {result['id']}")
except requests.exceptions.RequestException as e:
    print(f"Ошибка создания заказа: {e}")

Обработка ошибок

Коды ответов

  • 200 — успешная обработка
  • 400 — неверные данные запроса
  • 401 — неверный API ключ
  • 422 — ошибка валидации данных
  • 500 — внутренняя ошибка сервера

Примеры ошибок

Ошибка валидации

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "contact", "name"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Ошибка аутентификации

{
  "detail": "Invalid API key"
}

Мониторинг и логи

Статистика в веб-интерфейсе

В панели управления отображается: - Общее количество заказов - Количество обработанных заказов - Процент успешной обработки

Логирование

Приложение ведет подробные логи всех операций: - Создание заказов - Обработка заказов - Ошибки интеграции с Битрикс24 - Системные ошибки

Безопасность

Рекомендации по безопасности

1. Храните API ключ в безопасности

  • Не передавайте ключ в открытом виде
  • Используйте переменные окружения
  • Регулярно обновляйте ключи

2. Валидация данных

  • Проверяйте все входящие данные
  • Используйте HTTPS для передачи данных
  • Ограничивайте размер запросов

3. Мониторинг

  • Следите за статистикой обработки
  • Проверяйте логи на наличие ошибок
  • Настройте уведомления о критических ошибках

Поддержка

Получение помощи

  • Документация — используйте встроенную документацию в веб-интерфейсе
  • Логи — проверяйте логи для диагностики проблем
  • API тестирование — используйте интерактивную документацию для тестирования

Часто задаваемые вопросы

Q: Как часто обрабатываются заказы?

A: Заказы обрабатываются в фоновом режиме каждые несколько минут.

Q: Можно ли изменить логику обработки контактов?

A: Да, используйте параметр contact_behavior в API запросе.

Q: Что делать если заказ не обработался?

A: Проверьте логи, убедитесь что API ключ корректный, и что данные в Битрикс24 доступны для записи.

Заключение

Приложение "Заявки с сайта" предоставляет мощный инструмент для автоматизации приема и обработки заказов с интеграцией в Битрикс24. Используйте данное руководство для эффективной работы с системой и настройки интеграций с внешними источниками данных.