Developer Platform & Integrations

Шаг 1: Регистрация вкладки в карточке сделки CRM

// Исполняется один раз при установке локального приложения в Битрикс24:
BX24.callMethod('placement.bind', {
  PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
  HANDLER: 'https://app.checkspace.io/integrations/bitrix24/deal-tab',
  TITLE: 'Чек-лист CheckSpace',
  DESCRIPTION: 'Инспекция объекта и фотофиксация состояния'
}, function(res) {
  if (res.error()) {
    console.error('Ошибка регистрации вкладки:', res.error());
  } else {
    console.log('Вкладка успешно зарегистрирована в CRM_DEAL_DETAIL_TAB');
  }
});

Шаг 2: Обработчик во вкладке сделки (deal-tab.html)

<!DOCTYPE html>
<html>
<head>
  <script src="//api.bitrix24.com/api/v1/"></script>
  <script src="https://app.checkspace.io/static/sdk/checkspace-sdk.js"></script>
</head>
<body>
  <div id="audit-container" style="height: 600px;"></div>

  <script>
    BX24.init(function() {
      // Получаем контекст текущей открытой сделки в Битрикс24
      const placementInfo = BX24.placement.info();
      const dealId = placementInfo.options.ID;

      // Монтируем видоискатель CheckSpace
      CheckSpaceSDK.mount('#audit-container', {
        token: 'cs_live_session_deal_' + dealId,
        onComplete: function(result) {
          // 1. Публикуем результат в таймлайн сделки Битрикс24
          BX24.callMethod('crm.timeline.comment.add', {
            fields: {
              ENTITY_ID: dealId,
              ENTITY_TYPE: 'deal',
              COMMENT: 'Инспекция CheckSpace успешно пройдена!\n' +
                       'Оценка объекта: ' + result.scorePercent + '%\n' +
                       'Критических замечаний: ' + result.stopFactorsFailed
            }
          });
        },
        onStopFactorAlert: function(alertItem) {
          // 2. Блокируем сделку и переводим в статус фиксации дефекта
          BX24.callMethod('crm.deal.update', {
            id: dealId,
            fields: {
              STAGE_ID: 'BLOCKED_DEFECT',
              COMMENTS: 'Блокирующий стоп-фактор в чек-листе: ' + alertItem.title
            }
          });
        }
      });
    });
  </script>
</body>
</html>

<?php
// В файле app/views/desktop/orders/view.php
// Используем стандартный системный хелпер UI Kilemkhan ERP:
echo \Core\Helpers\UI::button([
    'text' => 'Аудит чистоты и дефектов ковра',
    'type' => 'dark',
    'size' => 'md',
    'icon' => 'camera',
    'attributes' => [
        'id' => 'btn-kkh-checkspace-audit',
        'data-order-id' => $order['id'],
        'data-workshop-id' => $order['workshop_id'] ?? 1
    ]
]);
?>

<!-- Подключаем JS SDK и обработчик открытия модалки -->
<script src="https://app.checkspace.io/static/sdk/checkspace-sdk.js"></script>
<script>
document.getElementById('btn-kkh-checkspace-audit')?.addEventListener('click', function() {
    const orderId = this.dataset.orderId;
    const workshopId = this.dataset.workshopId;

    CheckSpaceSDK.openModal({
        token: 'cs_kkh_live_token',
        locationId: 'workshop-' + workshopId,
        templateId: 'tpl-carpet-inspection-v1',
        onComplete: function(res) {
            // Мгновенное обновление бейджа проверки в карточке заказа
            showToast('Чек-лист по заказу #' + orderId + ' успешно зафиксирован (' + res.scorePercent + '%)', 'success');
            setTimeout(() => window.location.reload(), 1200);
        },
        onStopFactorAlert: function(alertData) {
            showToast('Стоп-фактор: ' + alertData.title, 'danger');
        }
    });
});
</script>

<?php
namespace App\Controllers;

use Core\Controller;
use Core\Database;

class CheckspaceWebhookController extends Controller
{
    private string $webhookSecret = 'whsec_kkh_secret_key_2026';

    public function handle(): void
    {
        // 1. Проверка HMAC-SHA256 подписи
        $rawRequestInput = file_get_contents('php://input');
        $signature = $_SERVER['HTTP_X_CHECKSPACE_SIGNATURE'] ?? '';

        $expectedSig = hash_hmac('sha256', $rawRequestInput, $this->webhookSecret);
        if (!hash_equals($expectedSig, $signature)) {
            http_response_code(401);
            echo json_encode(['error' => 'Invalid HMAC signature']);
            return;
        }

        $eventMessage = json_decode($rawRequestInput, true);
        $eventName = $eventMessage['event'] ?? '';
        $inspection = $eventMessage['data'] ?? [];

        $db = Database::getInstance();

        // 2. Обработка событий проверки
        if ($eventName === 'inspection.completed') {
            $orderId = $inspection['metadata']['order_id'] ?? null;
            $score = $inspection['score_percent'] ?? 100;
            $hasViolations = ($inspection['stop_factors_failed'] ?? 0) > 0;

            if ($orderId) {
                // Обновляем статус готовности ковра к выдаче или сушке
                $stmt = $db->prepare("
                    UPDATE orders 
                    SET inspection_status = :status,
                        inspection_score = :score,
                        inspection_photo_hash = :hash,
                        updated_at = NOW()
                    WHERE id = :id
                ");
                $stmt->execute([
                    ':status' => $hasViolations ? 'FLAGGED_DEFECT' : 'PASSED',
                    ':score' => $score,
                    ':hash' => $inspection['photo_hash'] ?? null,
                    ':id' => $orderId
                ]);
            }
        } elseif ($eventName === 'stop_factor.triggered') {
            // Критический дефект оборудования (центрифуга, роторный станок)
            $equipmentId = $inspection['equipment_id'] ?? null;
            if ($equipmentId) {
                // Блокируем доступ оператора к оборудованию до устранения
                $stmt = $db->prepare("UPDATE workshop_equipment SET status = 'SERVICE_REQUIRED' WHERE id = :id");
                $stmt->execute([':id' => $equipmentId]);
            }
        }

        header('Content-Type: application/json');
        echo json_encode(['status' => 'success', 'received_event' => $eventName]);
    }
}

Авторизация запросов

curl -X GET "https://app.checkspace.io/api/v1/locations" \
  -H "X-API-Key: cs_live_a8f94b12c98d41e" \
  -H "Accept: application/json"

Таблица основных маршрутов API