Integration of 1C-Bitrix with FIAS

1C-Bitrix Integration with FIAS

FIAS (Federal Information Address System) is the official state address registry of Russia. Integration is required when addresses must match the Federal Tax Service database, for working with shipping carriers, and for address form autocomplete tied to the official registry.

FIAS connection options

Option 1. Local FIAS database — download the full dump (~10 GB in XML, ~5 GB after import into PostgreSQL), deploy in your own database. Pros: no dependency on external services, full control. Cons: the database updates weekly, requiring a synchronization process.

Option 2. Third-party service APIs — DaData, Fias.nalog.ru API, GeoSuggest. Easier to integrate, but subject to request limits and external dependency.

Option 3. Ready-made Bitrix modules — several address suggestion modules with FIAS are available in the marketplace. Price: 3,000–15,000 RUB. Suitable for standard forms.

FIAS database structure

Key tables (after importing XML into PostgreSQL or MySQL):

The AOGUID field is the globally unique identifier of an address object (FIAS ID). This is the value to store in orders and pass to shipping carriers.

Querying the local FIAS database

// Search for streets by name within a specified city
function searchFiasStreets(string $cityGuid, string $streetName): array {
    $connection = \Bitrix\Main\Application::getConnection();
    $streetName = $connection->getSqlHelper()->forSql($streetName);

    $sql = "
        SELECT ao.AOGUID, ao.FORMALNAME, ao.SHORTNAME
        FROM fias_ADDROBJ ao
        WHERE ao.PARENTGUID = '{$cityGuid}'
          AND ao.AOLEVEL = 7  -- level: street
          AND ao.LIVESTATUS = 1 -- active records only
          AND LOWER(ao.FORMALNAME) LIKE LOWER('%{$streetName}%')
        LIMIT 20
    ";

    $result = $connection->query($sql);
    $rows = [];
    while ($row = $result->fetch()) {
        $rows[] = [
            'guid'  => $row['AOGUID'],
            'name'  => $row['FORMALNAME'] . ' ' . $row['SHORTNAME'] . '.',
        ];
    }
    return $rows;
}

Order form autocomplete

Set up a simple Ajax handler on the server (component or controller):

// ajax_handler.php in the component directory
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $type  = $_POST['type'];  // 'region', 'city', 'street', 'house'
    $query = trim($_POST['query']);
    $parent= $_POST['parent_guid'] ?? null;

    $results = FiasSearch::search($type, $query, $parent);
    header('Content-Type: application/json');
    echo json_encode(['suggestions' => $results]);
    die();
}

On the frontend — jQuery Autocomplete or a custom implementation with sequential selection: region → city/settlement → street → building. Each selection passes the AOGUID of the chosen object as parent_guid for the next level.

Updating the FIAS database

FIAS is updated every week. Use delta updates (not a full dump) for incremental updates:

1. Download the delta file from the FIAS website (fias.nalog.ru/updates).
2. Parse the XML and update the tables via INSERT ... ON DUPLICATE KEY UPDATE or UPSERT in PostgreSQL.
3. Automate the process with a Bitrix agent or a weekly cron job.

Processing time for a delta update on a mid-range server: 15–30 minutes. Full import from scratch: 2–4 hours.

Storing FIAS IDs in orders

Create the following order property fields:

• FIAS_REGION_GUID — region GUID.
• FIAS_CITY_GUID — city/settlement GUID.
• FIAS_STREET_GUID — street GUID.
• FIAS_HOUSE_GUID — building GUID (if present in the FIAS database).

These GUIDs are passed directly to the CDEK, Boxberry, and Russian Post APIs — they accept FIAS IDs for accurate determination of the delivery branch.