Соберите УПД и счёт-фактуру в XML формата ФНС 5.03

УПД, счёт-фактура и ДОП в XML для ЭДО (формат ФНС 5.03)

Область: сборка и проверка файлов обмена ON_NSCHFDOPPR — титул продавца УПД (СЧФДОП), счёта-фактуры (СЧФ) и документа об отгрузке (ДОП) для загрузки к любому оператору ЭДО (Диадок, СБИС, Такском, ЭДО Лайт, 1С-ЭДО). Не путать с commerceml_ru (обмен 1С↔сайт), fns_xml_ru (2-НДФЛ/3-НДФЛ/ЕГРЮЛ) и accounting_docs_ru (та же первичка, но в Excel).

Нормативная база: приказ ФНС от 19.12.2023 № ЕД-7-26/970@ в редакции приказа от 15.11.2024 № ЕД-7-26/1032@. Версия формата — только 5.03. Форматы 5.01 и 5.02 недействительны с 01.04.2025: оператор ЭДО отклоняет такой файл, а пользователь видит отказ уже после загрузки.

Главное правило

Собранный файл не патчится — ни регуляркой, ни побайтово, ни правкой текста: ошибка XSD означает неверный doc, его и чинить, а потом пересобирать save_upd_xml. Патч мимо сборщика ломает ИдФайл, кодировку windows-1251 и повторяется при каждом следующем запуске.

Табличная часть передаётся целиком — со всеми денежными колонками, какие есть в исходнике. rows_to_positions сам находит суммы, НДС и итог по строке; они попадают в XML как напечатаны, а не пересчитываются. Отсюда и reconcile_with_source(report, positions=positions) без expected_total: ожидаемый итог берётся из колонки исходника, а сверка расчёта с самим собой ничего не доказывает.

Конвертация, а не пересборка

Исходный документ — единственный источник содержания. Задача звучит как «переделай в XML», но по сути это перенос: то, что напечатано в присланном файле, обязано оказаться в XML без изменений и без потерь.

• Табличная часть входит в документ только через rows_to_positions. Разбирать таблицу самостоятельно — по координатам ячеек (df.iloc[7, 3]), regex'ом по тексту, «на глаз» из превью — запрещено: именно так теряются строки с объединёнными ячейками и переносами в наименовании.
• Строка без наименования больше не пропускается молча: rows_to_positions падает и называет отброшенные строки. Служебные строки (итог, разделитель, повтор шапки) пропускаются только явным allow_partial=True — и это решение надо озвучить клиенту.
• Реквизиты берутся из исходника дословно: наименования, ИНН/КПП, адреса, номер и дата документа, основание передачи. Переформулировать, сокращать, «причёсывать» — нельзя.
• Чего в исходнике нет — спросить. Заглушки, «типовые» значения и данные из прошлых документов не подставлять.
• Суммы не пересчитываются, если они напечатаны: колонки суммы без налога, НДС и стоимости с налогом переносятся как есть, расчёт остаётся только запасным вариантом для колонок, которых в таблице нет. Расхождение до копейки — округление исходника, и побеждает исходник; расхождение больше копейки — ошибка сборки с обоими числами, и чинится оно в исходнике или в разметке колонок, а не подгонкой.
• XSD и контрольные соотношения проверяют файл сам по себе: собранный из половины таблицы документ проходит их полностью. Единственное, что связывает результат с исходником, — reconcile_with_source.

Ловушки формата — источник почти всех отказов операторов

Обязательные блоки

• Файл — ИдФайл, ВерсФорм="5.03", ВерсПрог (все три required).
• Документ — КНД="1115131", Функция, ДатаИнфПр, ВремИнфПр.
• СвСчФакт — НомерДок, ДатаДок, СвПрод, СвПокуп, ДенИзм.
• ТаблСчФакт — минимум одна СведТов (обязателен НалСт и блок СумНал) плюс ВсегоОпл с СумНалВсего.
• СвПродПер — для СЧФДОП и ДОП: СодОпер и либо ОснПер (договор/спецификация), либо БезДокОснПер. У ОснПер обязательны все три реквизита — наименование, номер и дата. Если в исходнике напечатано только «Основной договор» без номера и даты, дату не выдумывать: спросить клиента либо убрать основание из передача — тогда соберётся БезДокОснПер, и это надо назвать в ответе.
• Подписант — СпосПодтПолном и ФИО; блок обязателен, документ без него не проходит XSD.

ИдФайл строится по шаблону ON_NSCHFDOPPR_{ИНН+КПП продавца}_{ИНН+КПП покупателя}_{ГГГГММДД}_{UUID}_0_0_0_0_0_00 и обязан совпадать с именем файла — за это отвечает make_id_fajl, имя возвращает save_upd_xml. Переименовывать файл после сборки нельзя.

fns_upd — фасад, из него доступно всё:

• save_upd_xml(doc, output_dir="/home/user/output") → путь; build_upd_xml(doc) → (имя, байты).
• validate_upd_xml(path|bytes) → {"valid", "errors", "warnings", "summary", "reconciled"}; format_report(report) — печатный вид.
• reconcile_with_source(report, expected_rows=None, expected_total=None, positions=None) — сверка готового XML с исходником; расхождение по числу позиций или итогу переводит отчёт в valid=False. Ожидаемый итог берётся из колонки исходника; переданный вручную expected_total, который с ней расходится, сам становится ошибкой. Без ожидаемых значений отказывает: сверять не с чем.
• rows_to_positions(rows, mapping=None, default_rate=None, allow_partial=False) — DataFrame / list[dict] / list[list] → позиции; распознаёт русские заголовки, подставляет ОКЕИ по единице измерения. Возвращает PositionList с source_rows, dropped, totals (уйдёт в XML) и source_totals (напечатано в исходнике).
• line_amounts(line) — суммы одной позиции той же арифметикой, что и сборка; normalize_rate(value), guess_okei(unit), totals_of(positions), nds_amount(base, rate), money, fns_date, fns_time, make_id_fajl.
• Имена колонок в mapping и ключи позиций — одни и те же: наим, кол, ед, океи, цена, сумма_без_ндс, ставка, ндс, сумма_с_ндс, артикул, признак. Таблица, названная этими именами, разбирается без mapping.

Структура doc:

Контрагент с ИНН из 12 цифр автоматически собирается как ИП (нужны фамилия/имя), из 10 — как юрлицо. сумма_без_ндс в позиции имеет приоритет над цена × кол — так переносятся строки со скидкой; расхождение уходит в warnings, не в ошибку.

Ограничения

• Скилл собирает титул продавца. Ответный титул покупателя (ON_NSCHFDOPPK) и приём входящих УПД сюда не входят.
• Электронная подпись не формируется: файл загружается в ЭДО неподписанным, подпись накладывает оператор.
• <СвОЭДОтпр> (идентификаторы участников ЭДО) не заполняется — оператор проставляет их при отправке.
• ТОРГ-12 и акт выполненных работ — другие приказы и другие XSD, этим скиллом не покрываются.