Інтеграція 1С-Бітрікс із Контур.Бухгалтерією: автоматизація обміну

Ручна передача даних гальмує бізнес

Невеликий інтернет-магазин на 1С-Бітрікс продає, а бухгалтер веде облік у Контур.Бухгалтерії. Щомісяця бухгалтер вручну переносить дані про продажі, накладні та оплати — це займає 2–4 години монотонної роботи. Помилки при копіюванні призводять до розбіжностей: одна зайва цифра в ІПН — і податкова вимагає уточнень. Ми стикалися з кейсами, де через це затримувалася здача звітності, а штрафи за неправильні дані сягали 20% від суми операції. Рішення — налаштувати автоматичний обмін через REST API Контур.Бухгалтерії. Це виключає людський фактор, скорочує час обробки замовлення до секунд і гарантує, що документи потрапляють у бухгалтерію без запізнень. Автоматизація бухгалтерського обліку у 60 разів швидша за ручний спосіб. Наша команда має 5+ років досвіду в інтеграції Бітрікса із зовнішніми сервісами та реалізувала понад 30 подібних проєктів. Ми пропонуємо інтеграцію під ключ: від аудиту поточної схеми до запуску та моніторингу. Замовте консультацію — оцінимо ваш проєкт і запропонуємо терміни.

REST API Контур.Бухгалтерії для автоматизації обліку

Контур.Бухгалтерія надає REST API (документація: https://api.kontur.ru/budget/v1/). Авторизація через OAuth 2.0 або API-ключ (залежить від тарифу). Доступні сутності: контрагенти, договори, документи (накладні, акти, рахунки), банківські операції, статті витрат. Для інтернет-магазину ключові операції: створення та пошук контрагентів за ІПН, створення документів реалізації (накладні, акти) та фіксація оплат. Автоматизація в 60 разів швидша за ручне введення — 2–5 секунд проти 2–5 хвилин на одне замовлення. API має обмеження 100 запитів на хвилину, що достатньо навіть для високонавантажених магазинів. При мережевих помилках ми використовуємо retry з експоненційною затримкою, щоб гарантувати доставку кожного документа. Інтеграція повністю відповідає вимогам 54-ФЗ, забезпечуючи коректну фіксацію оплат.

Авторизація в API

class KonturBukhClient {
    private string $apiKey;
    private string $accountId; // ID організації в Контур.Бухгалтерії
    private string $baseUrl = 'https://api.kontur.ru/budget/v1';

    public function __construct(string $apiKey, string $accountId) {
        $this->apiKey = $apiKey;
        $this->accountId = $accountId;
    }

    public function request(string $method, string $path, array $data = []): array {
        $url = "{$this->baseUrl}/accounts/{$this->accountId}{$path}";
        $ch = curl_init($url);
        $options = [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                "X-Api-Key: {$this->apiKey}",
            ],
        ];

        if ($method === 'POST' || $method === 'PUT') {
            $options[CURLOPT_CUSTOMREQUEST] = $method;
            $options[CURLOPT_POSTFIELDS] = json_encode($data);
        } elseif ($method === 'GET' && $data) {
            $url .= '?' . http_build_query($data);
            curl_setopt($ch, CURLOPT_URL, $url);
        }

        curl_setopt_array($ch, $options);
        $response = json_decode(curl_exec($ch), true);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new \RuntimeException("Kontur API error {$httpCode}: " . json_encode($response));
        }

        return $response ?? [];
    }
}

Синхронізація контрагентів

Перед створенням документа потрібно переконатися, що контрагент існує в Контур.Бухгалтерії. Типова помилка — спроба створити документ без попередньої синхронізації. Ми використовуємо пошук за ІПН: якщо контрагент вже є, використовуємо його ID; якщо ні — створюємо нового. Це запобігає дублюванню записів.

public function findOrCreateContragent(\Bitrix\Sale\Order $order): string {
    $props = $order->getPropertyCollection();
    $inn = $props->getItemByOrderPropertyCode('INN')->getValue();
    $name = $props->getItemByOrderPropertyCode('COMPANY')->getValue();

    // Пошук за ІПН
    $found = $this->client->request('GET', '/counterparties', ['inn' => $inn]);
    if (!empty($found['items'])) {
        return $found['items'][0]['id'];
    }

    // Створення нового
    $contragent = $this->client->request('POST', '/counterparties', [
        'name' => $name,
        'inn' => $inn,
        'kpp' => $props->getItemByOrderPropertyCode('KPP')->getValue() ?? '',
        'type' => 'LegalEntity',
    ]);

    return $contragent['id'];
}

Створення накладних з Бітрікса

При зміні статусу замовлення на «Відвантажено» створюємо накладну в Контур.Бухгалтерії. Використовуємо подію OnSaleStatusOrder.

AddEventHandler('sale', 'OnSaleStatusOrder', function(string $statusId, \Bitrix\Sale\Order $order) {
    if ($statusId !== 'D') return; // D = Доставляється/Відвантажено
    $service = new KonturBukhSyncService();
    $service->createInvoiceForOrder($order);
});

public function createInvoiceForOrder(\Bitrix\Sale\Order $order): void {
    $contragentId = $this->findOrCreateContragent($order);
    $orderNumber = $order->getField('ACCOUNT_NUMBER');
    $items = [];
    foreach ($order->getBasket() as $item) {
        $items[] = [
            'name' => $item->getField('NAME'),
            'quantity' => $item->getQuantity(),
            'price' => $item->getPrice(),
            'vatRate' => $this->getVatRate($item), // 'none'|'vat0'|'vat10'|'vat20'
            'unit' => 'шт.',
        ];
    }
    $document = $this->client->request('POST', '/documents/saleinvoices', [
        'date' => date('Y-m-d'),
        'number' => $orderNumber,
        'counterpartyId' => $contragentId,
        'items' => $items,
        'totalAmount' => $order->getPrice(),
        'comment' => 'Автоматично створено із замовлення #' . $orderNumber,
    ]);
    // Зберігаємо ID документа у властивостях замовлення
    $order->setField('COMMENTS', $order->getField('COMMENTS') . "\nID документа КБ: " . $document['id'] );
    $order->save();
}

Фіксація оплат

При зміні статусу оплати замовлення на «Оплачено»:

AddEventHandler('sale', 'OnSalePaymentPaid', function(\Bitrix\Sale\Payment $payment) {
    $order = $payment->getOrder();
    $documentId = $this->getKonturDocumentId($order->getId()); // зі сховища
    if (!$documentId) return;
    $this->client->request('POST', "/documents/saleinvoices/{$documentId}/payments", [
        'date' => date('Y-m-d'),
        'amount' => $payment->getSum(),
        'paymentMethod' => $payment->getPaySystem()->getField('CODE') === 'cash' ? 'Cash' : 'BankTransfer',
    ]);
});

Зберігання зв'язків

Таблиця local_kontur_bukh_sync:

CREATE TABLE local_kontur_bukh_sync (
    ORDER_ID INT PRIMARY KEY,
    KB_DOC_ID VARCHAR(100),
    SYNCED_AT DATETIME,
    STATUS ENUM('pending','synced','error') DEFAULT 'pending',
    ERROR_MSG TEXT
);

Як налаштувати інтеграцію за 5 кроків?

1. Отримати API-ключ в особистому кабінеті Контур.Бухгалтерії.
2. Встановити PHP-клієнт (код вище) на сервер з Бітріксом.
3. Налаштувати відповідність полів користувацьких властивостей замовлення та сутностей API.
4. Зареєструвати обробники подій OnSaleStatusOrder та OnSalePaymentPaid.
5. Провести тестову синхронізацію на staging-оточенні та запустити моніторинг.

Додатково налаштовується система сповіщень: при помилках синхронізації надсилається алерт на пошту або в Telegram. Це дозволяє оперативно реагувати на збої.

Чи потрібна технічна підтримка?

Так, ми надаємо гарантію на роботу інтеграції та технічну підтримку. У разі помилок надсилаємо сповіщення та відновлюємо синхронізацію.

Що входить у роботу з інтеграції