Інтеграція 1С-Бітрікс із системою ЕДО Такськом

Інтеграція 1С-Бітрікс з системою ЕДО Такском

Такском — один з акредитованих операторів ЕДО з власним API і сервісами для різних обсягів документообігу: від 50 до десятків тисяч документів на місяць. Компанії, вже підключені до Такском для податкової звітності (ФСРАР, ФНП), часто надають перевагу використанню того самого оператора для ЕДО — один договір, одна точка обслуговування. Інтеграція з 1С-Бітрікс дозволяє автоматизувати відправку документів за подіями в інтернет-магазині.

Особливості API Такском

Такском надає REST API (https://edo.taxcom.ru/api/). Авторизація — через Client Credentials OAuth 2.0:

class TaxcomClient
{
    private string $baseUrl = 'https://edo.taxcom.ru/api/v1';
    private string $accessToken;

    public function __construct(
        private string $clientId,
        private string $clientSecret
    ) {
        $this->accessToken = $this->getAccessToken();
    }

    private function getAccessToken(): string
    {
        $cached = \Bitrix\Main\Data\Cache::createInstance();
        if ($cached->startDataCache(3500, 'taxcom_token', '/taxcom/')) {
            $response = $this->httpPost('https://auth.taxcom.ru/oauth/token', [
                'grant_type'    => 'client_credentials',
                'client_id'     => $this->clientId,
                'client_secret' => $this->clientSecret,
                'scope'         => 'edo',
            ]);
            $cached->endDataCache(['token' => $response['access_token']]);
            return $response['access_token'];
        }
        $data = $cached->getVars();
        return $data['token'];
    }
}

Токен кешується на 3500 секунд (трохи менше години життя токена) — звичайний патерн для OAuth Client Credentials.

Створення та відправка документа

public function sendDocument(\Bitrix\Sale\Order $order): array
{
    $xmlContent = $this->generateUPDXml($order);

    // Крок 1: завантаження файлу
    $uploadResponse = $this->apiPost('/documents/upload', [
        'FileName'    => "UPD_{$order->getId()}.xml",
        'Content'     => base64_encode($xmlContent),
        'ContentType' => 'application/xml',
    ]);

    $fileId = $uploadResponse['FileId'];

    // Крок 2: підписання (КриптоПро або хмарний підпис Такском)
    $signature = $this->signFile($xmlContent);

    // Крок 3: відправка документа
    return $this->apiPost('/messages/send', [
        'RecipientBoxId' => $this->getRecipientBoxId($order),
        'Documents' => [[
            'FileId'    => $fileId,
            'Signature' => base64_encode($signature),
            'DocType'   => 'UniversalTransferDocument',
            'Function'  => 'ДОП',
        ]],
    ]);
}

Такском підтримує хмарний підпис через сервіс «Такском-Крипто» — сертифікат зберігається на стороні Такском, підписання відбувається через API без КриптоПро на сервері. Це спрощує інфраструктуру.

Пошук BoxId контрагента

public function findRecipientBoxId(string $inn, string $kpp = ''): ?string
{
    $response = $this->apiGet('/organizations/search', [
        'inn' => $inn,
        'kpp' => $kpp,
    ]);

    foreach ($response['Organizations'] as $org) {
        if ($org['Inn'] === $inn && ($kpp === '' || $org['Kpp'] === $kpp)) {
            return $org['BoxId'];
        }
    }
    return null;
}

При першому документі компанії — пошук BoxId за ІНН/КПП, збереження у користувацькому полі покупця Бітрікс (UF_TAXCOM_BOX_ID).

Кейс: ЕДО для медичного дистриб'ютора

Дистриб'ютор медвитратних матеріалів, ~400 B2B-клієнтів, що працює з державними лікарнями та приватними клініками. Державні установи часто мають власних ЕДО-операторів з роумінгом, частина працює через Такском напряму.

Особливість: крім УПД, для медичних товарів вимагаються акти приймання-передачі з розширеними реквізитами (серія, термін придатності, реєстраційне посвідчення). Стандартний формат УПД не покриває всі поля.

Рішення:

Розроблено складовий документ: УПД + анотація з розширеними медичними реквізитами як додатковий XML-файл у тому самому повідомленні Такском. Обидва файли підписуються одним підписом.

$documents = [
    [
        'FileId'    => $updFileId,
        'Signature' => base64_encode($updSignature),
        'DocType'   => 'UniversalTransferDocument',
    ],
    [
        'FileId'    => $annexFileId,
        'Signature' => base64_encode($annexSignature),
        'DocType'   => 'Attachment',  // доповнення до основного документа
        'Comment'   => 'Медичні реквізити товарів',
    ],
];

У Бітрікс реквізити товарів (серія, термін придатності) зберігаються як властивості позицій замовлення. При генерації XML витягуються з \Bitrix\Sale\BasketItem::getPropertyCollection().

Моніторинг черги документів

Для контролю документообігу — адміністративний розділ у Бітрікс з таблицею відправлених документів:

Замовлення → Документ Такском → Статус → Дата підписання

Дані беруться з таблиці local_taxcom_documents + періодичний polling API Такском для оновлення статусів (cron кожні 10 хвилин).

Склад робіт

• Налаштування акаунта Такском, отримання Client ID/Secret
• Налаштування хмарного підпису або КриптоПро
• Розробка PHP-клієнта Taxcom API
• Генерація XML-документів (УПД, Акти, складові документи)
• Довідник BoxId контрагентів у Бітрікс
• Подієва відправка при зміні статусу замовлення
• Моніторинг статусів, адміністративний розділ

Терміни: базова інтеграція — 3–5 тижнів. Зі складовими документами та розширеними типами — 6–9 тижнів.