אינטגרציית Bitrix + Kontur.Elba: חשבוניות אוטומטיות

אינטגרציית Bitrix + Kontur.Elba: חשבוניות אוטומטיות

Elba הוא שירות ענן לניהול חשבונאות מס עבור עצמאים במס פשוט ופטנט. בניגוד ל-MoeDelo ו-Kontur.Accounting, Elba מותאם לעסקים זעירים עם פעולות פשוטות. ה-API של Elba מספק גישה למסמכים (חשבוניות, אישורי ביצוע) ולצדדים מתקשרים, אך לא לניהול תשלומים. זה מגדיר את האפשרויות והמגבלות של אינטגרציה עם Bitrix.

אנחנו צוות עם 10 שנות ניסיון בפיתוח 1C-Bitrix ומומחים מוסמכים "1C-Bitrix". האינטגרציה שלנו פותרת את הבעיה של הפקת חשבוניות ואישורי ביצוע אוטומטיים מהזמנות בחנות המקוונת ישירות ל-Elba. הזמינו אינטגרציה במפתח פתוח—אנחנו נתחשב בכל הפרטים הספציפיים של העסק שלכם.

בעיות שאנחנו פותרים

הזנת חשבוניות ידנית. ללא אינטגרציה, מנהל מעתיק נתונים ידנית מ-Bitrix ל-Elba—שגיאות, עיכובים, אובדן לקוחות. הפתרון שלנו מבטל את הגורם האנושי, וחוסך עד 15 שעות בשבוע על הזנת נתונים.

OAuth 2.0 ללא שגיאות. שמירת מטמון שגויה של טוקנים מובילה לחסימות API. אנחנו מיישמים זרימת Client Credentials נכונה עם חידוש יזום.

מגבלות API של Elba. אין API לתשלומים ומגבלות בקשות—אנחנו מציעים פתרונות חלופיים: webhooks ממערכות תשלום, תור באמצעות סוכני Bitrix. זה מאפשר לנו לטפל בעד 1000 הזמנות ביום ללא חסימות.

איך להגדיר OAuth 2.0 עבור Elba

האימות מתבצע באמצעות פרוטוקול OAuth 2.0 (Client Credentials). עבור אינטגרציה בשרת, מספיק לקבל client_id ו-client_secret מלוח הבקרה של Elba.

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 של Elba ב-PHP

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) ?? [];
    }
}

איך להפיק חשבוניות אוטומטית מ-Bitrix?

התרחיש המרכזי: כאשר נוצרת הזמנה, אנחנו מייצרים אוטומטית חשבונית ב-Elba ושולחים אותה ללקוח במייל. לשם כך, קודם כל אנחנו מוצאים או יוצרים צד מתקשר לפי מספר עוסק מורשה (INN), ולאחר מכן יוצרים מערך של פריטי מוצרים.

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

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 של Elba ואיך לעקוף אותן?

אין API לרישום תשלומים. כאשר הזמנה משולמת ב-Bitrix, אי אפשר לסמן אוטומטית את החשבונית כמשולמת ב-Elba דרך ה-API. פתרון חלופי: webhook ממערכות תשלום → הודעת מייל לרואה החשבון עם מספר החשבונית. או להשתמש באינטגרציה הבנקאית של Elba—כאשר הכסף מגיע לחשבון, Elba עצמו מתאים את התשלום לחשבונית שהונפקה.

מגבלות API. ל-API של Elba יש מגבלות קצב בקשות. עבור חנות עם מספר גדול של הזמנות—תור שליחה דרך 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']; } } או worker נפרד.

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

אישור ביצוע עבודה עבור שירותים

עבור שירותים (לא סחורה), אנחנו מייצרים אישור ביצוע במקום חשבונית:

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

השוואת שירותים

Elba עדיף לעסקים זעירים, אבל הוא נופל מ-Kontur.Accounting בפונקציונליות—לאחרון יש APIs לתשלומים ותעודות משלוח.

מיפוי שדות: Bitrix → Elba

מה כלול בעבודה

אנחנו מספקים פתרון מוכן במפתח פתוח:

• אינטגרציית OAuth 2.0 עם שמירת מטמון טוקנים
• לקוח PHP עבור ה-API של Elba
• חיפוש ויצירת צדדים מתקשרים
• הפקת חשבוניות אוטומטית בעת יצירת הזמנה
• טיפול בשגיאות, רישום לוגים, ניסיונות חוזרים
• תיעוד והדרכת צוות
• אחריות ל-3 חודשים על פעילות תקינה

תהליך העבודה

1. ניתוח—אנחנו לומדים את זרימת המסמכים שלכם, מזהים נקודות אינטגרציה.
2. עיצוב—אנחנו מפתחים את הארכיטקטורה, מסכמים על המחסנית (גרסת PHP, Bitrix).
3. פיתוח—אנחנו כותבים קוד, מגדירים סוכנים, בודקים בסביבת staging.
4. בדיקות—אנחנו בודקים את המחזור המלא: הזמנה → חשבונית → תשלום → הודעה.
5. פריסה—אנחנו מעלים לשרת הייצור, עוקבים אחרי הימים הראשונים.

לוחות זמנים ועלות

לוחות זמנים: בין 2 ל-4 שבועות תלוי במורכבות (קיום שדות לא טיפוסיים, תרחישי תשלום לא סטנדרטיים).

האינטגרציה בדרך כלל מחזירה את ההשקעה תוך 3 חודשים בזכות חיסכון בזמן המנהלים. קבלו ייעוץ ממהנדס—אנחנו נחשב את העלות המדויקת ואת לוחות הזמנים עבור הפרויקט שלכם.

התיעוד הרשמי של ה-API של Elba זמין ב-https://api.e-kontur.ru.