Имена полей и сверка

Как назвать поля схемы, чтобы сервис не только спросил модель, но и сам прочитал таблицы, сверил итоги с документом и отдал числа и даты в одном формате.

Универсальный эндпоинт отвечает по любой схеме, но точность двух сортов. Модель читает документ и заполняет вашу схему — это работает для любых имён полей. Поверх модели работает детерминированный слой: он читает векторные таблицы PDF и листы Excel сам, сверяет суммы, веса и число мест с итогами, напечатанными в документе, и перезаписывает ответ модели там, где сам уверен. Этот слой узнаёт поля схемы по именам. Назовите их из списка ниже — и получите не «ответ модели», а «ответ, сверенный с документом».

Как это выглядит в ответе

{
  "result": { "packages_total": 14, "items": [ { "name": "ACCESSORY PARTS", "gross_weight": 11.0 } ] },
  "metadata": {
    "extraction_status": "full",
    "verification": { "status": "verified", "checks": [], "checks_total": 82, "checks_ok": 82, "coverage": 0.556 },
    "profile": { "number_format": "eu", "tables": 29, "multidoc": true, "grand_total": { "packages": 14.0, "gross_weight": 5240.21 } }
  }
}

metadata.verification.status — verified (итоги документа сошлись с тем, что отдано), unverified (документ сам себе противоречит: в ответе ещё и extraction_status: "unverified", а расхождения — в warnings[] кодом verification_mismatch), no_reference (документ не печатает итогов — сверять нечем).
checks_total / checks_ok — сколько инвариантов найдено и сколько сошлось; наружу идут только несошедшиеся.
coverage — доля полей схемы, которые закрыл детерминированный слой.
include: ["provenance"] показывает, откуда взято каждое значение (source: "grid" — из таблицы, "derived" — разнесено из итога места, "llm" — от модели) со страницей и координатами; include: ["structure"] — дерево документа: места, позиции внутри мест, итоги по листам.

Рекомендуемые имена полей

Имя сравнивается без учёта регистра по вхождению: gross_weight_total, total_gross_weight, брутто_итого — всё узнаётся. Ключи схемы держите в snake_case латиницей, человеческий заголовок — в title.

Реквизиты (скаляры)

Что это	Имя поля (любое из)	Откуда берётся детерминированно
ИНН, КПП, ОГРН, БИК, р/с, к/с	`inn`, `kpp`, `ogrn`, `bik`, `account`, `corr_account`; с ролью — `supplier_inn`, `buyer_kpp`	грамматики с контрольными суммами; при двух ИНН модель получает кандидатов
Мест всего	`packages_total`, `total_colli`, `number_of_colli`	итог документа или единственного листа
Брутто / нетто итого	`gross_weight_total`, `net_weight_total`, `total_gross_weight`	итог документа
Итого (сумма)	`total`, `amount_total`, `сумма_итого`	строка «Total / Итого» инвойса
Дата	`date`, `invoice_date` (тип `string`, `format: date`)	пара «ключ: значение» документа, всегда в ISO
Номер упаковочного листа, поставки, проекта, заказа	`packing_list_no`, `delivery_no`, `project_number`, `order_number`	шапка пакинга
Контейнер, пломба, место	`container_number`, `seal_number`, `package_number`	шапка / подвал пакинга
Обозначение, масштаб (чертёж)	`designation`, `scale`	штамп ЕСКД

Позиции (свойства элементов массива)

Колонка документа	Имя свойства (любое из)
Артикул / обозначение / part number	`article`, `designation`, `part_no`, `sku`
Наименование / описание	`name`, `description`, `service`, `goods`
Количество	`quantity`, `qty`, `количество`
Единица	`unit`, `uom`
Цена	`price`, `unit_price`, `цена`
Сумма	`amount`, `total_price`, `сумма`
НДС	`vat`, `tax`
Нетто / брутто	`net_weight`, `gross_weight`, `нетто`, `брутто`
Объём	`volume`, `m3`
Мест / коробок	`packages`, `colli`, `boxes`, `cartons`
Габариты	`dimensions`, `размер`
Код ТН ВЭД	`hs_code`
Материал, примечание, позиция	`material`, `note`, `position`

Имя массива — любое (items, positions, rows); важен состав свойств элемента: чтобы таблица привязалась, нужно совпадение хотя бы двух колонок.

Что происходит с полем, которого нет в списке

Оно уходит модели как есть — точно так же, как в кабинете колонка, добавленная словами. Сверки по нему не будет, но и ничего не сломается.

Числа и даты — один формат на выходе

Числа. type: number / integer получают число, как бы оно ни было напечатано: «1 200,50», «1.450,000», «€ 22.500,00», «CNY98,000.00», «84.575 Pieces». Формат чисел документа (европейский или английский) сервис определяет по однозначным формам — «2.000» в европейском документе это две тысячи, а не два. Валюта и единица уходят в provenance/structure, в число не попадают.
Даты. type: string с format: date приходят строго YYYY-MM-DD: «07.11.2024», «31-JUL-2026», «AUG.19, 2025», «21 июля 2025 г.» приводятся на сервере после ответа модели. Нераспознанная дата остаётся как напечатана, а не превращается в мусор. Модель format не видит — под маской structured-режима она ломала даты.
Пустое поле — пустое. Перечень кандидатов вместо значения («66123 (SALES ORDER NO), 1485731 (PACKING LIST)») и абзац-объяснение («в документе отсутствует…») вычищаются с warning ambiguous_scalar: поля в документе нет.

Что сверяется

Инвариант	Где	Как отдаётся
Σ позиций = итог листа / документа (мест, брутто, нетто, объём, сумма, количество)	пакинги, инвойсы, спецификации	`verification.checks[]` с `declared` / `computed` / `delta`
нетто ≤ брутто в строке	пакинги	то же
количество × цена = сумма в строке	инвойсы	то же
габариты × = объём	пакинги с размерами	то же
число записей = число мест	пакинги (уровень без колонки количества)	то же; при потере строк — `unverified`
×1000 — потерянный разделитель тысяч в европейском формате	любые	коррекция + warning `number_format_corrected`

Сверка относится только к тому, что реально ушло в ответ: таблицы измерений протокола испытаний или графы бланка, которых схема не просила, статус не портят.

Линии сетки для этого не обязательны. Проформа или инвойс, распечатанный из браузера, где позиции разделены только пробелами, разбирается по координатам слов: сервис находит строку заголовков, режет строки позиций на колонки, приклеивает многострочные описания к своей позиции, пропускает «Carry over» и берёт «Total» как итог. Артикул в строке позиции и описание под ним становятся полями article и name, единица из «1 Piece» — полем unit.

Несколько документов в одном файле

Подшивку сканов (инвойс + упаковочный лист + CMR + декларация) режьте split: {"mode": "auto"} — границы ищутся по титулам страниц на русском, английском, немецком, турецком, китайском и итальянском, а модель привлекается только к страницам без единого признака. У каждой секции — doc_type с номером («Инвойс 383180»). Подробнее — в «Разбиение».