שילוב ביטריקס עם קונטור.אקאונטינג: אוטומציה של החלפת נתונים

העברת נתונים ידנית מאטה את העסק

חנות מקוונת קטנה מוכרת דרך Bitrix, בעוד רואה החשבון מנהל רישומים ב-Kontur.Accounting. בכל חודש, רואה החשבון מעביר ידנית נתוני מכירות, חשבוניות ותשלומים — דבר שלוקח 2–4 שעות של עבודה מונוטונית. שגיאות העתקה מובילות לפערים: ספרה אחת נוספת במספר ע.מ. ומשרד המס דורש הבהרות. נתקלנו במקרים שבהם זה עיכב דיווחים, וקנסות על נתונים שגויים הגיעו ל-20% מסכום העסקה. הפתרון הוא הגדרת החלפה אוטומטית דרך REST API של Kontur.Accounting. זה מבטל את הגורם האנושי, מקצר את זמן עיבוד ההזמנות לשניות, ומבטיח שמסמכים מגיעים למחלקת הנהלת החשבונות ללא עיכובים. לצוות שלנו יש ניסיון של למעלה מ-5 שנים בשילוב Bitrix עם שירותים חיצוניים, וביצענו יותר מ-30 פרויקטים כאלה. אוטומציה יכולה לחסוך עד 14–20 אלף דולר בשנה בעלויות עבודה חשבונאיות, וגם להפחית את הסיכון לקנסות. אנו מציעים שילוב מפתח ביד: מבדיקת הסכימה הנוכחית ועד השקה וניטור. בקשו ייעוץ — נעריך את הפרויקט שלכם ונספק לוחות זמנים.

Kontur.Accounting API לאוטומציה של הנהלת חשבונות

Kontur.Accounting מספקת תיעוד REST API. אימות דרך OAuth 2.0 או מפתח API (תלוי בתעריף). ישויות זמינות: צדדים נגדיים, חוזים, מסמכים (חשבוניות, מעשים, חשבונות), פעולות בנקאיות, פריטי הוצאות. עבור חנות מקוונת, הפעולות המרכזיות הן: יצירה וחיפוש של צדדים נגדיים לפי ע.מ., יצירת מסמכי מכירה (חשבוניות, מעשים), ורישום תשלומים. אוטומציה מהירה פי 60 מהזנה ידנית — 2–5 שניות לעומת 2–5 דקות להזמנה. ל-API יש מגבלה של 100 בקשות לדקה, וזה מספיק אפילו לחנות עם תעבורה גבוהה. לשגיאות רשת, אנו משתמשים בניסיון חוזר עם השהיה אקספוננציאלית כדי להבטיח מסירה של כל מסמך. אנו תומכים גם בפורמט CommerceML להחלפת נתונים ומבטיחים עמידה ב-54-FZ למסמכים פיסקליים.

אימות ב-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 ?? [];
    }
}

סנכרון צדדים נגדיים

לפני יצירת מסמך, יש לוודא שהצד הנגדי קיים ב-Kontur.Accounting. טעות אופיינית היא ניסיון ליצור מסמך ללא סנכרון מוקדם. אנו משתמשים בחיפוש לפי ע.מ.: אם הצד הנגדי כבר קיים, השתמשו במזהה שלו; אם לא, צרו חדש. זה מונע רשומות כפולות.

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'];
}

יצירת מסמך מכירה

כאשר סטטוס ההזמנה משתנה ל"נשלח", צרו חשבונית ב-Kontur.Accounting. השתמשו באירוע 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 ?? []; } } .

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',
    ]);
});

שמירת קשרים

טבלת 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']; } :

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 בחשבון האישי של Kontur.Accounting.
2. התקינו את לקוח ה-PHP (הקוד למעלה) על השרת עם Bitrix.
3. מפו את שדות ההזמנה המותאמים אישית לישויות ה-API.
4. רשמו מטפלי אירועים עבור 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(); } .
5. בצעו סנכרון בדיקה בסביבת staging והשיקו ניטור.

בנוסף, מוגדרת מערכת התראות: במקרה של שגיאות סנכרון, נשלחת התראה במייל או בטלגרם. זה מאפשר תגובה מהירה לתקלות.

מה כלול בעבודת השילוב