Integration of 1C-Bitrix with the Taxcom electronic document management system

1C-Bitrix Integration with Taxcom EDI System

Taxcom is one of the accredited EDI operators with its own API and services for varying document volumes — from 50 to tens of thousands of documents per month. Companies already connected to Taxcom for tax reporting (FSRAR, FTS) often prefer to use the same operator for EDI — one contract, one point of contact. Integration with 1C-Bitrix enables automatic document dispatch triggered by events in the online store.

Taxcom API Specifics

Taxcom provides a REST API (https://edo.taxcom.ru/api/). Authorization uses 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'];
    }
}

The token is cached for 3,500 seconds (slightly less than the token's one-hour lifetime) — the standard pattern for OAuth Client Credentials.

Creating and Sending a Document

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

    // Step 1: upload the file
    $uploadResponse = $this->apiPost('/documents/upload', [
        'FileName'    => "UPD_{$order->getId()}.xml",
        'Content'     => base64_encode($xmlContent),
        'ContentType' => 'application/xml',
    ]);

    $fileId = $uploadResponse['FileId'];

    // Step 2: sign the document (CryptoPro or Taxcom cloud signature)
    $signature = $this->signFile($xmlContent);

    // Step 3: send the document
    return $this->apiPost('/messages/send', [
        'RecipientBoxId' => $this->getRecipientBoxId($order),
        'Documents' => [[
            'FileId'    => $fileId,
            'Signature' => base64_encode($signature),
            'DocType'   => 'UniversalTransferDocument',
            'Function'  => 'ДОП',
        ]],
    ]);
}

Taxcom supports cloud signing via the "Taxcom-Crypto" service — the certificate is stored on Taxcom's side, signing occurs via API without CryptoPro on the server. This simplifies the infrastructure.

Finding a Counterparty 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;
}

On the first document for a company — search BoxId by INN/KPP, save to a custom buyer field in Bitrix (UF_TAXCOM_BOX_ID).

Case Study: EDI for a Medical Distributor

A medical supplies distributor, ~400 B2B clients, serving public hospitals and private clinics. Government institutions often have their own EDI operators with roaming; some work directly through Taxcom.

Specific requirement: in addition to UPD, medical goods require acceptance-transfer acts with extended fields (batch number, expiry date, registration certificate). The standard UPD format does not cover all required fields.

Solution:

A composite document was developed: UPD + annotation with extended medical fields as an additional XML file in the same Taxcom message. Both files are signed with a single signature.

$documents = [
    [
        'FileId'    => $updFileId,
        'Signature' => base64_encode($updSignature),
        'DocType'   => 'UniversalTransferDocument',
    ],
    [
        'FileId'    => $annexFileId,
        'Signature' => base64_encode($annexSignature),
        'DocType'   => 'Attachment',  // supplement to the main document
        'Comment'   => 'Medical product details',
    ],
];

Product attributes (batch number, expiry date) are stored as order line item properties in Bitrix. During XML generation they are retrieved from \Bitrix\Sale\BasketItem::getPropertyCollection().

Document Queue Monitoring

For document flow oversight — an admin section in Bitrix with a table of sent documents:

Order → Taxcom Document → Status → Signing Date

Data is pulled from the local_taxcom_documents table with periodic polling of the Taxcom API to update statuses (cron every 10 minutes).

Scope of Work

• Taxcom account setup, obtaining Client ID/Secret
• Cloud signature or CryptoPro setup
• PHP Taxcom API client development
• XML document generation (UPD, Acts, composite documents)
• Counterparty BoxId directory in Bitrix
• Event-driven dispatch on order status change
• Status monitoring, admin panel

Timeline: basic integration — 3–5 weeks. With composite documents and extended document types — 6–9 weeks.