Russian ETRN Builder

PHP библиотека для создания электронных транспортных накладных (ЭТрН) в формате ФНС.

Описание

Библиотека предназначена для генерации XML документов электронных транспортных накладных в соответствии с требованиями ФНС России. Поддерживает создание всех титулов ЭТрН документов.

Поддерживаемые титулы

Титул	Код документа	Описание	Статус
Т1	ON_TRNACLGROT	Информация о грузе, ТС, водителе (Грузоотправитель)	✅ Поддерживается
Т2	ON_TRNACLPPRIN	Принятие груза к перевозке (Перевозчик)	🚧 В разработке
Т3	ON_TRNACLGRPO	Приемка груза, состояние при выгрузке (Грузополучатель)	🚧 В разработке
Т4	ON_TRNACLPVYN	Выдача груза, замечания по выгрузке (Перевозчик)	🚧 В разработке

Требования

• PHP >= 8.1
• Расширение DOM для PHP

Установка

Через Composer

composer require maxistyle/russian-etrn-builder

Ручная установка

1. Скачайте библиотеку
2. Подключите автозагрузчик:

require_once 'vendor/autoload.php';

Быстрый старт

Создание титула Т1

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MaxiStyle\EtrnBuilder\DocumentGenerator;
use MaxiStyle\EtrnBuilder\Entities;

// Создаем контакты грузоотправителя
$contact = new Entities\Contact();
$contact->set('phone', '+7 222 888 44 44');

// Создаем адрес грузоотправителя
$address = new Entities\Address();
$address->set('full', 'Хабаровский край, г Хабаровск, Суворова улица 82А')
    ->set('countryCode', '643');

// Создаем юридическое лицо
$ul = new Entities\LegalEntity();
$ul->set('name', 'ООО "МНОГОВОЗОФФ"')
    ->set('inn', '2724218020')
    ->set('kpp', '272301001');

// Создаем сведения о грузоотправителе
$svGO = new Entities\Shipper();
$svGO->set('goEksp', 0) // грузоотправитель не является экспедитором
    ->set('ul', $ul)
    ->set('address', $address)
    ->set('contact', $contact);

// Создаем содержание информации грузоотправителя
$sodInfGO = new Entities\Shipment();
$sodInfGO->set('svGO', $svGO);

// Создаем документ Т1
$doc = new Entities\T1();
$doc->set('numTrN', 'ТН-001') // номер транспортной накладной
    ->set('numOrder', 'Без номера') // номер заказа
    ->set('dateTrN', new DateTime()) // дата транспортной накладной
    ->set('dateOrder', new DateTime()) // дата заказа
    ->set('dateFile', new DateTime()) // дата формирования файла
    ->set('sodInfGO', $sodInfGO);

// Генерируем XML
$generator = new DocumentGenerator();

try {
    $xml = $generator->generate($doc);
    $generator->saveToFile($xml, './example.xml');
    
    echo 'XML файл успешно создан!';
} catch (Exception $e) {
    echo 'Ошибка: ' . $e->getMessage();
}

Структура проекта

russian-etrn-builder/
├── src/
│   ├── DocumentGenerator.php      # Основной класс генерации
│   ├── Builders/                  # Билдеры для каждого титула
│   │   ├── DocumentBuilder.php    # Базовый билдер
│   │   ├── DocumentBuilderInterface.php
│   │   └── T1Builder.php         # Билдер для титула Т1
│   ├── Entities/                  # Сущности данных
│   │   ├── Address.php           # Адрес
│   │   ├── BaseEntity.php        # Базовый класс сущности
│   │   ├── Contact.php           # Контактная информация
│   │   ├── Document.php          # Базовый класс документа
│   │   ├── IP.php                # Индивидуальный предприниматель
│   │   ├── SodInfGO.php          # Содержание информации грузоотправителя
│   │   ├── SvGO.php              # Сведения о грузоотправителе
│   │   ├── T1.php                # Документ титула Т1
│   │   └── UL.php                # Юридическое лицо
│   └── Exception/                 # Исключения
│       ├── UnsupportedDocumentException.php
│       └── XMLGenerationException.php
├── examples/
│   └── t1.php                    # Пример создания титула Т1
├── composer.json
└── README.md

Основные классы

DocumentGenerator

Основной класс для генерации XML документов.

Методы:

• generate(object $document) - Генерирует XML строку
• saveToFile(string $xml, string $filename) - Сохраняет XML в файл с BOM
• generateToFile(object $document, string $filename) - Генерирует и сохраняет файл

Сущности данных

Все сущности наследуются от BaseEntity и имеют методы:

• get(string $name) - Получить значение свойства
• set(string $name, mixed $value) - Установить значение свойства

Основные сущности:

• T1 - Документ титула Т1
• UL - Юридическое лицо
• IP - Индивидуальный предприниматель
• Address - Адрес
• Contact - Контактная информация
• SvGO - Сведения о грузоотправителе
• SodInfGO - Содержание информации грузоотправителя

Обработка ошибок

Библиотека использует два типа исключений:

• UnsupportedDocumentException - Выбрасывается при попытке создать документ неподдерживаемого типа
• XMLGenerationException - Выбрасывается при ошибках генерации XML

try {
    $xml = $generator->generate($document);
} catch (MaxiStyle\EtrnBuilder\Exception\UnsupportedDocumentException $e) {
    echo "Неподдерживаемый тип документа: " . $e->getMessage();
} catch (MaxiStyle\EtrnBuilder\Exception\XMLGenerationException $e) {
    echo "Ошибка генерации XML: " . $e->getMessage();
}

Лицензия

Проект распространяется под лицензией MIT. Подробности в файле LICENSE.

Автор

MaxiStyle

• Email: tiranmax@yandex.ru

Поддержка

Для получения поддержки или сообщения об ошибках создавайте issues в репозитории проекта.

---

Библиотека разработана в соответствии с требованиями ФНС России для электронного документооборота транспортных накладных.