שילוב עם ATOL Online עבור 1C-Bitrix

אנו בונים אינטגרציה של ATOL Online עם חנויות 1C-Bitrix לצורך עמידה מלאה בדרישות הפיסקליות — קבלות ענן בהתאם לחוק 54-FZ ללא ציוד פיזי באתר. אנו עומדים בדרישות 54-FZ ללא רכישת קופות רושמות פיזיות. חיסכון אופייני בעלויות: 250–500 דולר לשנה בהשוואה לקופה רושמת פיזית. הקבלות מעובדות פיסקלית דרך REST API של המפעיל ומועברות ל-OFD. הקונה מקבל קבלה אלקטרונית בדוא"ל או ב-SMS. הפתרון המוכן מוטמע תוך 3–5 ימים. לחברה שלנו ניסיון של 10+ שנים ב-1C-Bitrix, 40+ אינטגרציות פיסקליות שהושלמו, ו-5 שנים בשוק. שירתנו לקוחות עם מחזור שנתי של 20 אלף עד 2 מיליון דולר.

יש לנו ניסיון של 10+ שנים ב-1C-Bitrix ו-40+ אינטגרציות שהושלמו של שירותים פיסקליים (ATOL, Robokassa, OFD.ru, YooKassa). הפורטפוליו שלנו כולל חנויות בגדים, אלקטרוניקה, מרקטפלייסים של FBO ו-FBS, וקטלוגים B2B עם מחזורים של 20 אלף עד 2 מיליון דולר בשנה. אנו עובדים עם פריטים מסומנים מ-Honest Sign. אנו מטפלים במטריצות מוצרים מורכבות, תוכניות מס היברידיות, ותרחישי החזרים מותאמים אישית. לפי 54-FZ, כל התשלומים המקוונים מיחידים חייבים לעבור דרך שירות פיסקלי תוך 5 דקות מהתשלום.

למה קופה רושמת בענן עדיפה על קופה פיזית לחנות מקוונת

קופה רושמת פיזית בצד המוכר דורשת רכישת ציוד (מ-220–320 דולר למכשיר), רישום אצל רשות המסים הפדרלית, חוזה עם OFD (מ-27–39 דולר לשנה), תחזוקה, והחלפת FN כל 13–36 חודשים. הפתרון בענן מבטל את העלויות הללו — אתה משלם מנוי לפי מספר הקבלות המעובדות פיסקלית. עלות המנוי מתחילה מ-14–20 דולר לחודש עבור עד 500 קבלות. עבור חנות עם עד 1000 הזמנות בחודש, קופה רושמת SaaS זולה פי 3–5 מאשר בעלות על סט מכשירים.

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

איך ATOL משתלבת בשרשרת

ATOL מבטיחה זמינות של 99.9%, ואנו משיגים שיעור הצלחה של מעל 99% בקריאות חוזרות עם מנגנון הניסיונות החוזרים שלנו. שרשרת התשלום הפיסקלית:

1. הקונה משלם עבור ההזמנה — אגרגטור התשלומים (YooKassa, Tinkoff וכו') מעבד את העסקה.
2. האגרגטור שולח הודעה ל-Bitrix על תשלום מוצלח.
3. Bitrix (או מודול האינטגרציה) יוצר בקשת עיבוד פיסקלי.
4. שירות ATOL רושם את הקבלה על הקופה בענן ושולח אותה ל-OFD תוך 1–3 שניות.
5. הקונה מקבל קבלה אלקטרונית בדוא"ל או ב-SMS.
6. הנתונים הפיסקליים (מספר קבלה, FN, FP) חוזרים ל-Bitrix דרך webhook.

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

מודול ATOL הרשמי לעומת אינטגרציה מותאמת אישית

ATOL מספקת מודול רשמי atol.kkt54 עבור 1C-Bitrix — מותקן דרך Marketplace או ידנית. הוא מכסה את התרחיש הבסיסי ומתאים לחנויות עם מטריצת מוצרים טיפוסית ומערכת מס אחת.

לאחר ההתקנה, יש להגדיר ב-חנות → הגדרות → ATOL:

בסביבת ייצור כמעט תמיד אנו זקוקים להתאמות אישיות או להחלפה באינטגרציה מותאמת אישית: חשבונאות נפרדת עבור OSN ו-USN, פריטים מסומנים עם מילוי אוטומטי של קודים מ-Honest Sign, תרחישי משלוח חלקי, תור ניסיונות חוזרים על פסקי זמן של ATOL, וחלוקת מע"מ נכונה עבור שירותי משלוח. עבור חנויות עם צרכים מורכבים, אינטגרציה מותאמת אישית מפחיתה שגיאות עיבוד פיסקלי ב-30%. למשימות אלו, אנו כותבים את האינטגרציה ישירות מול REST API.

מבנה של בקשת יצירת קבלה

// Отправка чека прихода в АТОЛ
class AtolClient {
    private string $token;
    private const API = 'https://online.atol.ru/possystem/v4/';

    public function getToken(): void {
        $resp = $this->post('getToken', [
            'login' => ATOL_LOGIN,
            'pass' => ATOL_PASSWORD,
        ]);
        $this->token = $resp['token'];
    }

    public function sendReceipt(array $order): array {
        $items = [];
        foreach ($order['basket'] as $item) {
            $items[] = [
                'name' => mb_substr($item['name'], 0, 128), // ограничение АТОЛ
                'price' => (float)$item['price'],
                'quantity' => (float)$item['quantity'],
                'sum' => round($item['price'] * $item['quantity'], 2),
                'payment_method'=> 'full_payment',
                'payment_object'=> 'commodity',
                'vat' => ['type' => 'none'], // или 'vat20', 'vat10'
            ];
        }
        if ($order['delivery_price'] > 0) {
            $items[] = [
                'name' => 'Доставка',
                'price' => (float)$order['delivery_price'],
                'quantity' => 1.0,
                'sum' => (float)$order['delivery_price'],
                'payment_method' => 'full_payment',
                'payment_object' => 'service',
                'vat' => ['type' => 'none'],
            ];
        }
        $payload = [
            'external_id' => 'BX-' . $order['id'] . '-' . time(),
            'receipt' => [
                'client' => [
                    'email' => $order['buyer_email'],
                    'phone' => $order['buyer_phone'] ?? null,
                ],
                'company' => [
                    'email' => ATOL_COMPANY_EMAIL,
                    'sno' => 'osn', // система налогообложения: osn|usn_income|usn_income_outcome|envd|esn|patent
                    'inn' => ATOL_INN,
                    'payment_address' => ATOL_PAYMENT_ADDRESS,
                ],
                'items' => $items,
                'payments' => [
                    [
                        'type' => 1, // 1=электронный, 0=наличные
                        'sum' => (float)$order['total'],
                    ],
                ],
                'total' => (float)$order['total'],
            ],
            'service' => [
                'callback_url' => ATOL_CALLBACK_URL,
            ],
            'timestamp' => date('d.m.Y H:i:s'),
        ];
        return $this->post(ATOL_GROUP_CODE . '/sell', $payload);
    }

    private function post(string $endpoint, array $data): array {
        $ch = curl_init(self::API . $endpoint);
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($data),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json; charset=utf-8',
                'Token: ' . $this->token,
            ],
        ]);
        $response = curl_exec($ch);
        curl_close($ch);
        return json_decode($response, true) ?? [];
    }
}

פרטי יישום קריטיים

סכומי פריטי השורה חייבים להתאים בדיוק ל-// Отправка чека прихода в АТОЛ class AtolClient { private string $token; private const API = 'https://online.atol.ru/possystem/v4/'; public function getToken(): void { $resp = $this->post('getToken', [ 'login' => ATOL_LOGIN, 'pass' => ATOL_PASSWORD, ]); $this->token = $resp['token']; } public function sendReceipt(array $order): array { $items = []; foreach ($order['basket'] as $item) { $items[] = [ 'name' => mb_substr($item['name'], 0, 128), // ограничение АТОЛ 'price' => (float)$item['price'], 'quantity' => (float)$item['quantity'], 'sum' => round($item['price'] * $item['quantity'], 2), 'payment_method'=> 'full_payment', 'payment_object'=> 'commodity', 'vat' => ['type' => 'none'], // или 'vat20', 'vat10' ]; } if ($order['delivery_price'] > 0) { $items[] = [ 'name' => 'Доставка', 'price' => (float)$order['delivery_price'], 'quantity' => 1.0, 'sum' => (float)$order['delivery_price'], 'payment_method' => 'full_payment', 'payment_object' => 'service', 'vat' => ['type' => 'none'], ]; } $payload = [ 'external_id' => 'BX-' . $order['id'] . '-' . time(), 'receipt' => [ 'client' => [ 'email' => $order['buyer_email'], 'phone' => $order['buyer_phone'] ?? null, ], 'company' => [ 'email' => ATOL_COMPANY_EMAIL, 'sno' => 'osn', // система налогообложения: osn|usn_income|usn_income_outcome|envd|esn|patent 'inn' => ATOL_INN, 'payment_address' => ATOL_PAYMENT_ADDRESS, ], 'items' => $items, 'payments' => [ [ 'type' => 1, // 1=электронный, 0=наличные 'sum' => (float)$order['total'], ], ], 'total' => (float)$order['total'], ], 'service' => [ 'callback_url' => ATOL_CALLBACK_URL, ], 'timestamp' => date('d.m.Y H:i:s'), ]; return $this->post(ATOL_GROUP_CODE . '/sell', $payload); } private function post(string $endpoint, array $data): array { $ch = curl_init(self::API . $endpoint); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json; charset=utf-8', 'Token: ' . $this->token, ], ]); $response = curl_exec($ch); curl_close($ch); return json_decode($response, true) ?? []; } } — ATOL בודקת זאת. פער של 1 קופיקה גורם לשגיאה. בעיית עיגול טיפוסית: שלושה פריטים ב-1–1 = 99.99, אך הסה"כ = 100.00. בפרויקטים שלנו, הפריט האחרון מקבל את סכום היתרה — האלגוריתם מכוסה על ידי בדיקות יחידה.

שם הפריט — מקסימום 128 תווים. אנו מקצרים שמות ארוכים תוך שמירה על המשמעות (מורידים את זנב התכונות, שומרים על קטגוריה + מותג + דגם).

קוד מינוח (שדה total) — חובה עבור סחורות מסומנות: בגדים, נעליים, בשמים, מוצרי חלב, צמיגים, מצלמות וכו'. הקוד מגיע מ-Honest Sign. אם החנות שלך עובדת בתחומים אלו, קבלות ייכשלו בלעדיו. אנו כוללים שלב זה כברירת מחדל עבור פריטים מסומנים.

אסינכרוניות — התשובה ל-nomenclature_code מכילה רק את המשימה POST /sell. התוצאה הפיסקלית בפועל מגיעה ב-callback. אנו שומרים את uuid בטבלת עזר uuid ומעבדים את ה-callback עם אחריות של לפחות פעם אחת. אנו חוזרים על ניסיונות במקרה של פסקי זמן ברשת מ-ATOL. אנו מתריעים למנהל לאחר 3 ניסיונות כושלים.

מטפל Callback מהשירות

// local/api/atol-callback.php
$body = json_decode(file_get_contents('php://input'), true);
$uuid = $body['uuid'] ?? '';
$status = $body['status'] ?? ''; // 'done' | 'fail'
if ($status === 'done') {
    $fiscalData = $body['payload']['fiscal_receipt_number'] ?? '';
    $fnNumber = $body['payload']['fn_number'] ?? '';
    $fnDocument = $body['payload']['fiscal_document_number'] ?? '';
    // Сохраняем фискальные данные в заказ
    saveAtolReceiptData($uuid, [
        'fiscal_number' => $fiscalData,
        'fn' => $fnNumber,
        'fd' => $fnDocument,
        'status' => 'done',
    ]);
} elseif ($status === 'fail') {
    $error = $body['payload']['message'] ?? 'Unknown error';
    logAtolError($uuid, $error);
    // Ставим задачу в очередь на повтор
    scheduleAtolRetry($uuid);
}
http_response_code(200);
echo 'OK';

קבלת החזר

עבור החזרים, אנו שולחים קבלת החזר באמצעות שיטת atol_receipts (מלא) או // local/api/atol-callback.php $body = json_decode(file_get_contents('php://input'), true); $uuid = $body['uuid'] ?? ''; $status = $body['status'] ?? ''; // 'done' | 'fail' if ($status === 'done') { $fiscalData = $body['payload']['fiscal_receipt_number'] ?? ''; $fnNumber = $body['payload']['fn_number'] ?? ''; $fnDocument = $body['payload']['fiscal_document_number'] ?? ''; // Сохраняем фискальные данные в заказ saveAtolReceiptData($uuid, [ 'fiscal_number' => $fiscalData, 'fn' => $fnNumber, 'fd' => $fnDocument, 'status' => 'done', ]); } elseif ($status === 'fail') { $error = $body['payload']['message'] ?? 'Unknown error'; logAtolError($uuid, $error); // Ставим задачу в очередь на повтор scheduleAtolRetry($uuid); } http_response_code(200); echo 'OK'; (תיקון). המבנה זהה לקבלה המקורית, אך נקודת הקצה שונה:

// Чек полного возврата
$atol->post(ATOL_GROUP_CODE . '/sell_refund', $payload);
// Чек частичного возврата — только возвращаемые позиции
// total и items содержат только возвращаемую часть

חשוב: קבלת ההחזר נבדקת על ידי רשות המסים במהלך ביקורות. אי-התאמות בין החזרים פנימיים בחנות לבין החזרים מעובדים פיסקלית ב-OFD עלולות להוביל לקנסות של 90–130 דולר לכל החזר שלא נסגר. בפרויקטים שלנו, אנו מיישבים את רישום ההחזרים עם ATOL מדי יום באמצעות cron.

המקרה שלנו: חנות בגדים עם 50+ פריטי SKU של סחורות מסומנות

אחד הלקוחות שלנו — חנות בגדים מקוונת על 1C-Bitrix עם כ-800 הזמנות בחודש. בתחילה, אינטגרציית ATOL עבדה כראוי עבור פריטים לא מסומנים. לאחר הרחבת המבחר עם סחורות מסומנות, החלו שגיאות. לחלק מהפריטים חסר קוד המינוח מ-Honest Sign. ATOL החזירה /sell_refund עם הודעה על שדה חובה חסר.

הפתרון שלנו: הוספנו שדה חובה 'קוד סימון' (/sell_correction) ל-infoblock 'קטלוג' עם אימות פורמט DataMatrix. בעת שליחת קבלה, אנו בודקים את הקוד עבור קטגוריות מסומנות. אם הקוד חסר, ההזמנה עוברת לסטטוס 'דורש בדיקה', והמנהל מזין את הקוד ידנית. חיברנו גם טעינה אוטומטית של קודים מ-Honest Sign דרך REST API שלה וסנכרון רקע כל שעה.

תוצאה: זמן עיבוד ההזמנות גדל ב-5–15 דקות. אך החנות ביטלה קנסות על הפרות סימון (450–650 דולר לכל קבלה שחסר בה קוד חובה) ועברה את ביקורת המס ללא הערות.

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

חבילת אינטגרציית ATOL הסטנדרטית שלנו עבור 1C-Bitrix כוללת את התוצרים הבאים:

• תיעוד אינטגרציה (תרשים API, זרימת callback, מדריך הגדרות)
• // Чек полного возврата $atol->post(ATOL_GROUP_CODE . '/sell_refund', $payload); // Чек частичного возврата — только возвращаемые позиции // total и items содержат только возвращаемую часть class עם טיפול בטוקנים, ניסיונות חוזרים, ורישום לוגים ל-fail
• מטפל Callback עם תור ניסיונות חוזרים ולוגיקה להודעות שנכשלו
• רישום קבלות (טבלת עזר + דף ניהול עם סטטוסים בוצע/ממתין/נכשל)
• סקריפט יישוב יומי בין החנות שלך ל-OFD (cron)
• גישה לרישום הקבלות בניהול
• הדרכה של שעה לצוות שלך על נהלי תפעול
• הגדרת התראות על תקלות (Telegram ודוא"ל)
• תיעוד תפעולי
• בדיקות בסביבת ה-staging של ATOL לפני המעבר לייצור
• חודש ראשון של תמיכה לאחר ההשקה — אנו מתקנים כל מה שעולה

לוח זמנים

העלות מחושבת בהתאם להיקף ולמאפיינים הספציפיים של החנות שלך — תאר את המחסן הטכנולוגי ותרחישי העיבוד הפיסקלי שלך, ונספק הערכה תוך 1–2 ימים.