Сверка заявленных показов с подтвержденными плеерами

GET /api/v1/plays/claims/verification

https://app.tanba-ooh.kz/api/v1/plays/claims/verification

Технический текст справочника написан на английском.

Право write:plays (тот же ключ, что передает заявки). Администратор и сотрудник рекламной платформы.

Для каждой строки заявки организации в периоде возвращает, сколько показов подтвердили плееры, и статус: matched (подтверждено все заявленное), over_claimed (подтверждено меньше заявленного, но не ноль), unmatched (ничего не подтверждено). verified это меньшее из заявленного и подтвержденного. Подтверждают показы, которые плеер пометил вашей организацией как продавцом (detail.src записи показа) и, если строка называет сделку, этой сделкой. Если у строки нет такой метки, считаются показы часа, которые не объясняются метками других продавцов, а строка получает untagged: true. Берется наибольшее по уровням доказательства число, а не сумма; basis_tier называет этот уровень, tiers показывает подтвержденное по уровням. Показы, переданные операторами из своих CMS, не доказательство и не учитываются.

Метка это указание источника, а не доказательство. Заявка не меняет начисления: тарификация идет только по показам плееров. Период from–to: даты (дни Asia/Almaty) или моменты RFC 3339, to не включается, не больше 62 дней.

Аутентификация

Ключ API в заголовке Authorization или сессия консоли.

Право доступа: write:plays

Параметры

Имя	Где	Тип	Обязательный	Описание	Пример
`from`	запрос	string	да	Начало периода: дата или момент RFC 3339.	`2026-10-06`
`to`	запрос	string	да	Конец периода, не включается.	`2026-10-07`

Ответы

200 Строка на каждую строку заявки в периоде.

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`from`	string	да	Start of the range.	`"2026-10-06T00:00:00+05:00"`
`to`	string	да	End of the range.	`"2026-10-07T00:00:00+05:00"`
`summary`	object	да	Totals over the lines.
`summary.lines`	integer		Number of claim lines in the range.	`2`
`summary.matched`	integer		Lines whose claim is fully proved.	`1`
`summary.over_claimed`	integer		Lines proved in part.	`1`
`summary.unmatched`	integer		Lines with nothing proved.	`0`
`summary.claimed`	integer		Plays claimed over all lines.	`238`
`summary.verified`	integer		Plays proved over all lines, each line capped at its claim.	`230`
`lines`	array of object	да	The claim lines in time order.
`lines[].structure_code`	string	да	Code of the structure.	`"ALM-0012"`
`lines[].approval_number`	string	да	Number of the approval of the line.	`"TNB-2026-000123"`
`lines[].hour`	string	да	The hour of the line in Asia/Almaty time.	`"2026-10-06T14:00:00+05:00"`
`lines[].deal_id`	string	да	Empty when the line names no deal.	`"deal-4411"`
`lines[].claimed`	integer	да	Plays claimed for the hour.	`118`
`lines[].verified`	integer	да	The smaller of the claim and the plays proved.	`110`
`lines[].status`	string	да	matched when all of the claim is proved, over_claimed when part, unmatched when none. matched, over_claimed, unmatched
`lines[].untagged`	boolean	да	True when no tag of the platform backs the line and all untagged plays of the hour were counted.	`false`
`lines[].basis_tier`	string \| null	да	Evidence tier of the proved plays; null when none. mtls, signed, attested, native, <nil>
`lines[].tiers`	object	да	Proved plays by evidence tier.	`{"mtls": 110}`

Пример

{
  "from": "2026-10-06T00:00:00+05:00",
  "to": "2026-10-07T00:00:00+05:00",
  "summary": {
    "lines": 2,
    "matched": 1,
    "over_claimed": 1,
    "unmatched": 0,
    "claimed": 238,
    "verified": 230
  },
  "lines": [
    {
      "structure_code": "ALM-0012",
      "approval_number": "TNB-2026-000123",
      "hour": "2026-10-06T14:00:00+05:00",
      "deal_id": "deal-4411",
      "claimed": 118,
      "verified": 110,
      "status": "over_claimed",
      "untagged": false,
      "basis_tier": "mtls",
      "tiers": {
        "mtls": 110
      }
    }
  ]
}

Ошибки

Ошибки приходят документом problem (application/problem+json) со стабильным полем code.

Статус	Значение
401	Нет действительной сессии или ключа API (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	Роль или право ключа этого не допускает (`forbidden`, `key_scope_denied`, `key_route_denied`).
422	Ошибки полей (`validation_failed`).
default	Ошибка в виде документа problem.

Примеры кода

curl

curl 'https://app.tanba-ooh.kz/api/v1/plays/claims/verification?from=2026-10-06&to=2026-10-07' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/plays/claims/verification?from=2026-10-06&to=2026-10-07",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://app.tanba-ooh.kz/api/v1/plays/claims/verification?from=2026-10-06&to=2026-10-07", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}