Prepaid approvals bought, used and left

GET /api/v1/billing/entitlements

https://app.tanba-ooh.kz/api/v1/billing/entitlements

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

Scope read:billing. The prepaid approval rate (7 000 tenge instead of 10 000) applies to a submission only while its billed organisation has a unit left: units bought minus the prepaid submissions that are submitted, in review or approved. A withdrawn or rejected submission returns its unit. The billed organisation is the operator of the structures, else the applicant. A caller sees its own organisation; the authority and the platform administrator see every organisation with a purchase or a prepaid submission, and the purchases recorded. A prepaid submission sent for review with no unit left is refused with the prepaid_balance problem (422) on POST /api/v1/submissions/{id}/submit.

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

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

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

Ответы

200 Balances and the purchases recorded, newest first.

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`more`	boolean		Есть и равно true, если покупок больше 200 и список обрезан.	`true`
`items`	array of PrepaidBalance	да	One balance per organisation.
`items[].org_id`	string (uuid)	да	Identifier of the organisation billed.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`items[].org_name`	string	да	Name of the organisation billed.	`"Alma Outdoor LLP"`
`items[].purchased`	integer (int64)	да	Prepaid approvals bought.	`20`
`items[].used`	integer (int64)	да	Prepaid submissions that are submitted, in review or approved.	`7`
`items[].balance`	integer (int64)	да	Units left; a prepaid submission is accepted while this is at least 1.	`13`
`purchases`	array of PrepaidPurchase	да	Purchases recorded for the visible organisations, newest first, up to 200.
`purchases[].id`	string (uuid)	да	Identifier of the purchase.	`"9d2f6a30-18c4-4e7b-a1d5-62b0c7e3f814"`
`purchases[].org_id`	string (uuid)	да	Organisation the units were bought for.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`purchases[].quantity`	integer	да	Approvals bought.	`20`
`purchases[].paid_on`	string \| null (date)	да	Day the payment was received; null when not stated.	`"2026-10-01"`
`purchases[].reference`	string	да	Invoice or payment the purchase rests on; may be empty.	`"Invoice 17"`
`purchases[].recorded_at`	string (date-time)	да	When the platform administrator recorded the purchase.	`"2026-10-02T09:00:00Z"`

Пример

{
  "more": true,
  "items": [
    {
      "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
      "org_name": "Alma Outdoor LLP",
      "purchased": 20,
      "used": 7,
      "balance": 13
    }
  ],
  "purchases": [
    {
      "id": "9d2f6a30-18c4-4e7b-a1d5-62b0c7e3f814",
      "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
      "quantity": 20,
      "paid_on": "2026-10-01",
      "reference": "Invoice 17",
      "recorded_at": "2026-10-02T09:00:00Z"
    }
  ]
}

Ошибки

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

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

Примеры кода

curl

curl 'https://app.tanba-ooh.kz/api/v1/billing/entitlements' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/billing/entitlements",
    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/entitlements", 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))
}