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.

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

Authorization тақырыбындағы API кілті немесе консоль сеансы.

Рұқсат: 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	No valid session or API key (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	The role or the key's scope does not allow this (`forbidden`, `key_scope_denied`, `key_route_denied`).
404	Nothing there, or not visible to the caller.
default	An error as a problem document.

Код мысалдары

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))
}