Как читать ведомость и проверять ее доказательства

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

Страницы справочника: Доказательства и офлайн-проверка и Форматы конверта согласования и списка отзыва.

Получите ведомость

В консоли откройте «Начисления», выберите период и скачайте ведомость в PDF на казахском, русском или английском языке. Те же цифры есть в API интеграции с правом read:billing:

curl -H 'Authorization: Bearer tnbk_EXAMPLE_secret' \
  'https://app.tanba-ooh.kz/api/v1/billing/periods/0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10'

Ведомость заканчивается строкой основания, например basis: 96240 plays, evidence tier: mtls, model: billing-v0. В ней сказано, сколько показов лежит в основе начисления, какой уровень доказательств их дал и какая модель множителей превратила показы в расчетные единицы. Доказательства замораживаются вместе с периодом: закрытый период всегда показывает те цифры, с которыми его закрыли.

Как читать строки

Каждая строка ответа это одно начисление:

Поле	Значение
`kind`	`impression` за показы, `approval_single` и `approval_prepaid` за сборы за согласование, `lab` за сбор лаборатории
`source_ref`	Для строки показов: конструкция и часы, которые она охватывает; для строки доначисления: конструкция и месяц; для строки сбора: номер согласования
`quantity`	Расчетные единицы. Для показов это число показов, умноженное на множитель формата конструкции в модели; в `billing-v0` он равен 1.000 для всех форматов, поэтому единицы равны показам
`amount_kzt`, `vat_kzt`	Сумма в тенге десятичной строкой без НДС и НДС
`tiers`	Уровни доказательств, давшие показы строки
`model`	Модель множителей; для строки сбора пусто

Два блока рядом со строками не дают картине исказиться:

reported_not_billed это показы, о которых сообщили за период, но которые не вошли в начисление: уровни вне набора, определяющего начисление, и строки, которые оператор импортировал из своей CMS (уровень import, никогда не тарифицируется). Разрыв виден раньше, чем кто-то примет решение о нем.
shortfalls перечисляет закрытые месяцы, по которым сейчас в хранилище показов меньше, чем было начислено. Их показывают уполномоченному органу, автоматически они не возвращаются.

Строка показов с названием <код> late <гггг-мм> один раз начисляет показы более раннего закрытого месяца, которые пришли после его закрытия, по тарифу того месяца.

Уровни доказательств

Уровень это канал, по которому пришли показы; он определяет, насколько им доверяют.

Уровень	Канал
`mtls`	Плеер с клиентским сертификатом, подписывающий свои пакеты (Передача показов)
`signed`	Плеер или агент с записанным ключом
`attested`	CMS оператора, которая ручается за свои плееры подписанным пакетом
`native`	Еще один канал, у которого есть учетные данные устройства
`import`	Строки, которые оператор импортировал из своей CMS через импорт показов; хранятся отдельно и никогда не тарифицируются

Для одной конструкции, согласования и часа показы разных уровней никогда не складываются: цифру дает уровень с наибольшим числом показов, поэтому экран, о котором сообщили и плеер, и CMS, тарифицируется один раз. Набор уровней, определяющих начисление, задает владелец платформы.

Проверьте доказательства сами

Для всего ниже нужны только tanba-verify, который можно скачать на странице Загрузки, и root.pem, корневой сертификат платформы, к которому восходят согласования, списки отзыва, якоря и печати. Корень тестового контура выдается вместе с тестовой средой; набор корневых сертификатов появится на странице загрузок, когда появится боевой корень.

1. Ежедневная печать полученной статистики

Каждый день по Алматы, вскоре после полуночи, платформа запечатывает пакеты статистики, полученные накануне: один корень Меркла по пакетам, подписанный ключом статуса, связанный с печатью предыдущего дня и записанный в публичный реестр. Публичны только счета и корень.

curl -o seal.json https://verify.tanba-ooh.kz/v1/stats-seals/2026-10-13
tanba-verify seal seal.json --ca root.pem

OK означает, что подпись принадлежит ключу статуса и восходит к корню, что тело то самое, которое подписано, и что доказательство реестра ведет от печати к корню ее дня реестра. Код выхода 0 это хорошо, 2 означает, что что-то не так, а 6 означает, что печать в порядке, но день реестра ее еще не включил: запросите ее позже. Принадлежность одного пакета к пакетам печати проверяется параметром --batch-proof, которому дают файл с путем Меркла этого пакета; публичного вызова, который выдавал бы такой файл, пока нет.

2. День реестра и Биткоин

Печать это лист дня реестра, в который она попала. Дайджест этого дня отмечен по времени в Биткоине. Пересчитайте дайджест по входным данным и проверьте доказательство:

curl -o ledger-2026-10-14.json https://verify.tanba-ooh.kz/v1/ledger-days/2026-10-14
curl -o ledger-2026-10-14.ots https://verify.tanba-ooh.kz/v1/ledger-days/2026-10-14/proof.ots
tanba-verify ledger --day 2026-10-14 --ots ledger-2026-10-14.ots --inputs ledger-2026-10-14.json \
  --btc-header-url https://blockstream.info/api

Код 0 значит, что доказательство несет блок Биткоина. Код 2 значит, что входные данные противоречат друг другу, 3 что доказательство относится к другому дайджесту, 6 что доказательство еще ожидает, а 8 что публичный обозреватель блоков не согласен. Без --btc-header-url заголовок блока здесь не проверяется; официальный ots verify -d DIGEST FILE.ots проверяет его по вашему собственному узлу.

3. Одно согласование в реестре

curl -o ledger-proof.json https://verify.tanba-ooh.kz/v1/approval/TNB-2026-000123/ledger-proof
tanba-verify inclusion --proof ledger-proof.json --approval TNB-2026-000123

Доказательство говорит, что лист согласования входит в дерево его дня. Оно доступно, когда день закрыт и записан.

4. Согласование, список отзыва и якорь

tanba-verify spot.mp4 spot.mp4.p7s --roots root.pem
tanba-verify revocations list.p7s --ca root.pem
tanba-verify anchor anchor-2026-10-05.p7s --ca root.pem

Первая команда проверяет медиафайл по конверту его согласования. Коды выхода: 0 OK, 2 BAD_SIGNATURE, 3 HASH_MISMATCH, 4 EXPIRED_APPROVAL, 5 NOT_YET_VALID и 64 для неверной команды или нечитаемого файла; 6 OUTER_NOT_VERIFIED и 7 OUTER_INVALID относятся к государственной подписи. Вторая команда печатает подписанный список отзыва, третья проверяет ежедневный якорь аудита, обе завершаются кодом 0 или 2. Форматы описаны в руководстве Форматы конверта согласования и списка отзыва.

5. Сохраненный пакет

Каждый принятый пакет показов хранится теми байтами, что получены, вместе с подписью и SHA-256 тела. Возьмите пакет, посчитайте его хэш, проверьте подпись открытым ключом устройства или установки CMS и пройдите по prev_sha256 и seq. Как это устроено, описано в руководстве Передача показов.

Чего доказательства не доказывают

Реестр показывает, что запись существовала в этот день и потом не менялась. Он не показывает, что решение, лежащее за записью, было верным. Печать охватывает то, что платформа получила; показ, о котором не сообщили, в ней не найти, а пропущенный отрезок виден как пробел в номерах записей плеера.