Интеграция 1С-Битрикс с Эльба (СКБ Контур)

Интеграция 1С-Битрикс с Эльба (СКБ Контур)

Эльба — облачный сервис налогового учёта для ИП на УСН и патенте. В отличие от МоёДело и Контур.Бухгалтерии, Эльба ориентирована на совсем маленький бизнес с упрощёнными операциями. API Эльбы ограничен: он предоставляет доступ к документам (счета, акты) и контрагентам, но не к полному управлению операциями. Это определяет возможности и ограничения интеграции с Битрикс.

Что доступно через API Эльбы

API Эльбы (https://api.e-kontur.ru/api/v1/): авторизация через OAuth 2.0 (Authorization Code или Client Credentials). Доступные ресурсы: counterparties (контрагенты), invoices (счета на оплату), acts (акты выполненных работ). Создание проводок по расходам и доходам напрямую через API — недоступно (только через UI Эльбы).

OAuth 2.0 авторизация

class ElbaOAuthService
{
    private string $clientId;
    private string $clientSecret;
    private string $redirectUri;
    private string $tokenUrl = 'https://auth.kontur.ru/connect/token';

    public function getClientCredentialsToken(): string
    {
        // Для серверной интеграции — Client Credentials flow
        $ch = curl_init($this->tokenUrl);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => http_build_query([
                'grant_type'    => 'client_credentials',
                'client_id'     => $this->clientId,
                'client_secret' => $this->clientSecret,
                'scope'         => 'elba.api',
            ]),
            CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
        ]);

        $response = json_decode(curl_exec($ch), true);
        curl_close($ch);

        // Кешируем токен на (expires_in - 60) секунд
        $this->cacheToken($response['access_token'], $response['expires_in'] - 60);

        return $response['access_token'];
    }
}

Клиент API

class ElbaApiClient
{
    private ElbaOAuthService $auth;
    private string $baseUrl = 'https://api.e-kontur.ru/api/v1';

    public function request(string $method, string $path, array $data = []): array
    {
        $token = $this->auth->getCachedToken();
        $ch    = curl_init($this->baseUrl . $path);

        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_HTTPHEADER     => [
                'Content-Type: application/json',
                "Authorization: Bearer {$token}",
            ],
            CURLOPT_POSTFIELDS => in_array($method, ['POST', 'PUT'])
                ? json_encode($data) : null,
        ]);

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

        if ($httpCode >= 400) {
            throw new \RuntimeException("Elba API error {$httpCode}: {$json}");
        }

        return json_decode($json, true) ?? [];
    }
}

Создание и поиск контрагентов

public function findOrCreateCounterparty(\Bitrix\Sale\Order $order): string
{
    $props = $order->getPropertyCollection();
    $inn   = $props->getItemByOrderPropertyCode('INN')?->getValue();
    $email = $props->getUserEmail();

    if ($inn) {
        // Поиск по ИНН
        $list = $this->client->request('GET', '/counterparties?inn=' . urlencode($inn));
        if (!empty($list)) {
            return $list[0]['id'];
        }
    }

    // Создание контрагента
    $isLegal = !empty($inn);
    $payload = $isLegal ? [
        'fullName' => $props->getItemByOrderPropertyCode('COMPANY')?->getValue() ?? '',
        'inn'      => $inn,
        'kpp'      => $props->getItemByOrderPropertyCode('KPP')?->getValue() ?? '',
        'email'    => $email,
    ] : [
        'fullName' => $props->getBuyerName(),
        'email'    => $email,
        'type'     => 'individual',
    ];

    $created = $this->client->request('POST', '/counterparties', $payload);
    return $created['id'];
}

Выставление счёта

Основной сценарий интеграции для ИП на УСН: при создании заказа автоматически формируем счёт в Эльбе и отправляем его покупателю по email.

public function createInvoiceForOrder(\Bitrix\Sale\Order $order): array
{
    $counterpartyId = $this->findOrCreateCounterparty($order);
    $items = [];

    foreach ($order->getBasket() as $item) {
        $items[] = [
            'name'     => $item->getField('NAME'),
            'count'    => $item->getQuantity(),
            'price'    => $item->getPrice(),
            'unit'     => 'шт.',
            'ndsRate'  => 'NoNds', // УСН — без НДС. Варианты: Nds0, Nds10, Nds20
        ];
    }

    // Доставка как отдельная позиция
    $deliveryPrice = $order->getField('PRICE_DELIVERY');
    if ($deliveryPrice > 0) {
        $items[] = [
            'name'    => 'Доставка',
            'count'   => 1,
            'price'   => $deliveryPrice,
            'unit'    => 'усл.',
            'ndsRate' => 'NoNds',
        ];
    }

    $invoice = $this->client->request('POST', '/invoices', [
        'number'          => $order->getField('ACCOUNT_NUMBER'),
        'date'            => date('Y-m-d'),
        'counterpartyId'  => $counterpartyId,
        'items'           => $items,
        'comment'         => 'Заказ с сайта #' . $order->getField('ACCOUNT_NUMBER'),
        'paymentDueDate'  => date('Y-m-d', strtotime('+3 days')),
    ]);

    return $invoice;
}

Ограничения Эльбы и обходы

Нет API для регистрации платежей. Когда заказ оплачен в Битрикс, автоматически отметить счёт оплаченным в Эльбе через API невозможно. Обход: webhook от платёжных систем → уведомление по email бухгалтеру с номером счёта. Или использовать банковскую интеграцию Эльбы — при поступлении денег на расчётный счёт Эльба сама сопоставляет платёж с выставленным счётом.

Лимиты API. У API Эльбы есть ограничения на количество запросов. Для магазина с большим числом заказов — очередь отправки через \Bitrix\Main\Agent или отдельный воркер.

Только счета и акты, не накладные. Для отгрузки товаров документ акта не вполне корректен юридически. Для ИП на УСН это обычно несущественно, но для ООО — рассмотрите Контур.Бухгалтерию.

Акт выполненных работ

Для услуг (не товаров) формируем акт вместо счёта:

public function createActForOrder(\Bitrix\Sale\Order $order, string $counterpartyId): array
{
    // Аналогичная структура items
    return $this->client->request('POST', '/acts', [
        'date'           => date('Y-m-d'),
        'counterpartyId' => $counterpartyId,
        'items'          => $this->buildItems($order),
        'comment'        => 'Услуги по заказу #' . $order->getField('ACCOUNT_NUMBER'),
    ]);
}

Состав работ

• OAuth 2.0 Client Credentials, кеш токена
• PHP-клиент Elba API
• Поиск и создание контрагентов
• Автоматическое выставление счетов по событию создания заказа
• Уведомления при оплате (workaround для отсутствия API платежей)
• Обработка ошибок, логирование, повторные попытки

Сроки: 2–4 недели с учётом OAuth, ограничений API и тестирования полного цикла.