Інтеграція 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 та тестування повного циклу.