One billing period with its accrual lines

GET /api/v1/billing/periods/{id}

https://app.tanba-ooh.kz/api/v1/billing/periods/{id}

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

Scope read:billing.

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

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

Право доступа: read:billing

Параметры

Имя	Где	Тип	Обязательный	Описание	Пример
`id`	путь	string (uuid)	да	Identifier of the billing period.	`0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10`

Ответы

200 The period.

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`period`	object	да	The billing period.
`period.id`	string (uuid)	да	Identifier of the billing period.	`"0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10"`
`period.org_id`	string (uuid)	да	Identifier of the organisation billed.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`period.org_name`	string		Name of the organisation billed.	`"Alma Outdoor LLP"`
`period.period_start`	string (date)	да	First day of the period.	`"2026-09-01"`
`period.period_end`	string (date)	да	Last day of the period.	`"2026-09-30"`
`period.status`	string	да	Whether the period is still accruing. open, closed
`period.closed_at`	string \| null		When the period was closed; null while it is open.	`"2026-10-02T09:00:00+05:00"`
`period.total_kzt`	string	да	Total of the period in tenge, as a decimal string.	`"1250000.00"`
`period.vat_kzt`	string	да	VAT on the total in tenge, as a decimal string.	`"150000.00"`
`period.statements`	integer		Number of statements issued for the period.	`2`
`lines`	array of BillingLine	да	The accrual lines of the period. A play line names the evidence tiers and the multiplier model behind it.
`lines[].id`	integer (int64)	да	Identifier of the line; the evidence pack of a play line is asked for with it.	`4711`
`lines[].kind`	string	да	What the line charges for. impression, approval_single, approval_prepaid, lab
`lines[].source_ref`	string	да	The structure and the hours of a play line (`S-001 2026-10-05T10..2026-10-20T11`), the structure and the month of a late line (`S-001 late 2026-09`), or the approval number of a fee line.	`"S-001 2026-10-05T10..2026-10-20T11"`
`lines[].quantity`	string	да	Billing units with three decimals. For a play line it is plays multiplied by the multiplier of the structure's format in the model (billing-v0 is 1.000 for every format, so units equal plays); for a fee line it is 1.	`"3739.000"`
`lines[].amount_kzt`	string	да	The line amount in tenge, without VAT	`"1869.50"`
`lines[].vat_kzt`	string	да	VAT on the line in tenge; 0.00 while the payee is not a VAT payer	`"0.00"`
`lines[].tiers`	array of string	да	Evidence tiers that gave the plays of the line (`mtls`, `signed`, `attested`, `native`). Per structure, approval and hour only the tier with the most plays counts. Empty for a fee line.	`["mtls", "signed"]`
`lines[].model`	string	да	Code of the multiplier model that turned plays into units; empty for a fee line.	`"billing-v0"`
`statements`	array of object	да	Statements issued for the period.
`reported_not_billed`	object	да	Plays reported in the period but outside the bill: tiers that are not in the billable set, and the hourly rows an operator imported from its own CMS (tier `import`, never billable). Per structure, approval and hour the larger figure counts.
`reported_not_billed.plays`	integer (int64)	да	All plays reported and not billed in the month	`1900`
`reported_not_billed.by_tier`	array of object	да	The same figure split by the tier it was reported on.
`reported_not_billed.by_tier[].tier`	string	да	The reporting channel. mtls, signed, attested, native, import
`reported_not_billed.by_tier[].plays`	integer (int64)	да	Plays reported on that tier and not billed	`1200`
`shortfalls`	array of BillingShortfall	да	Closed months of this organisation for which the plays now on file are fewer than were billed. They are shown for the authority and never credited automatically.
`shortfalls[].month`	string	да	The closed month	`"2026-09"`
`shortfalls[].structure`	string	да	Structure code	`"S-001"`
`shortfalls[].approval_number`	string	да	Approval the plays were counted against	`"TNB-2026-000001"`
`shortfalls[].billed_plays`	integer (int64)	да	Plays in the evidence of the closed bill	`2000`
`shortfalls[].current_plays`	integer (int64)	да	Billable plays on file now	`1500`

Пример

{
  "period": {
    "id": "0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10",
    "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
    "org_name": "Alma Outdoor LLP",
    "period_start": "2026-09-01",
    "period_end": "2026-09-30",
    "status": "open",
    "closed_at": "2026-10-02T09:00:00+05:00",
    "total_kzt": "1250000.00",
    "vat_kzt": "150000.00",
    "statements": 2
  },
  "lines": [
    {
      "id": 4711,
      "kind": "impression",
      "source_ref": "S-001 2026-10-05T10..2026-10-20T11",
      "quantity": "3739.000",
      "amount_kzt": "1869.50",
      "vat_kzt": "0.00",
      "tiers": [
        "mtls",
        "signed"
      ],
      "model": "billing-v0"
    }
  ],
  "statements": [
    {}
  ],
  "reported_not_billed": {
    "plays": 1900,
    "by_tier": [
      {
        "tier": "import",
        "plays": 1200
      }
    ]
  },
  "shortfalls": [
    {
      "month": "2026-09",
      "structure": "S-001",
      "approval_number": "TNB-2026-000001",
      "billed_plays": 2000,
      "current_plays": 1500
    }
  ]
}

Ошибки

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

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

Примеры кода

curl

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

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/billing/periods/0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10",
    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/billing/periods/0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10", 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))
}