PT EN

Resumo da carteira

URL base: $BUSINESS_API

O objecto

root_account_idstring · obrigatório

The caller's tenant, at the root of the portfolio.

periodobject · obrigatório

Reporting month.

Mostrar atributos filhos
labelstring · opcional
startstring (date-time) · opcional
endstring (date-time) · opcional
currencystring · obrigatório

Currency shared by every account in the portfolio.

accountsarray of object · obrigatório

The root account first, then each readable descendant account.

Mostrar atributos filhos
account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account. Omitted when unknown.

account_holder_namestring · opcional

Display name of the account holder. Omitted when unknown.

overviewobject · obrigatório

Domain totals and series are returned only when the caller has the corresponding domain read scope. Receivables require invoices:read or collections:read; collection_rate requires both invoices:read and payments:read. Portfolio overviews apply these checks separately to each account.

Mostrar atributos filhos
periodobject · opcional
currencystring · opcional
billed_centsinteger (int64) · opcional
collected_centsinteger (int64) · opcional
volume_m3number · opcional
readings_countinteger · opcional
collection_ratenumber · opcional

Percentage of the period's billed amount collected through payments applied to invoices billed in that period, capped at 100. Payments against earlier invoices are in arrears_collected_cents and do not raise this rate.

collected_current_period_centsinteger (int64) · opcional

Part of collected_cents applied to invoices billed in the period

arrears_collected_centsinteger (int64) · opcional

Part of collected_cents applied to invoices billed in earlier periods, or to no invoice

collections_by_hourobject · opcional

Collections for the utility's local today and yesterday, independent of the requested period

Mostrar atributos filhos
timezonestring · opcional
todayobject · opcional
yesterdayobject · opcional
read_ratenumber · opcional
open_workobject · opcional
Mostrar atributos filhos
incidentsinteger · opcional
ticketsinteger · opcional
work_ordersinteger · opcional
receivables_by_ageingarray of object · opcional
Mostrar atributos filhos
balance_centsinteger · opcional
bucketstring · opcional
invoicesinteger · opcional
seriesobject · opcional
Mostrar atributos filhos
billed_centsarray of SeriesPoint · opcional
collected_centsarray of SeriesPoint · opcional
volume_m3array of SeriesPoint · opcional
readingsarray of SeriesPoint · opcional
billed_centsinteger (int64) · obrigatório

Sum of billed_cents across the accounts.

collected_centsinteger (int64) · obrigatório

Sum of collected_cents across the accounts.

volume_m3number · obrigatório

Sum of volume_m3 across the accounts.

readings_countinteger · obrigatório

Sum of readings_count across the accounts.

seriesobject · obrigatório

Daily series summed across the accounts, oldest first.

Mostrar atributos filhos
billed_centsarray of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
collected_centsarray of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
volume_m3array of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
readingsarray of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
O objecto
{
  "root_account_id": "roo_202ZxesHbMupdaSf3oITN8C1tiu",
  "period": {
    "label": "2026-10",
    "start": "2026-11-19T09:30:00Z",
    "end": "2026-11-19T09:30:00Z"
  },
  "currency": "MZN",
  "accounts": [
    {
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "overview": {
        "period": {},
        "currency": "MZN",
        "billed_cents": 1,
        "collected_cents": 1,
        "volume_m3": 13.42,
        "readings_count": 1342,
        "collection_rate": 1,
        "collected_current_period_cents": 1,
        "arrears_collected_cents": 1,
        "collections_by_hour": {
          "timezone": "Africa/Maputo",
          "today": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          },
          "yesterday": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          }
        },
        "read_rate": 1,
        "open_work": {
          "incidents": 1,
          "tickets": 1,
          "work_orders": 1
        },
        "receivables_by_ageing": [
          {
            "balance_cents": 125000,
            "bucket": "bucket",
            "invoices": 1
          }
        ],
        "series": {
          "billed_cents": [
            {}
          ],
          "collected_cents": [
            {}
          ],
          "volume_m3": [
            {}
          ],
          "readings": [
            {}
          ]
        }
      }
    }
  ],
  "billed_cents": 1,
  "collected_cents": 1,
  "volume_m3": 13.42,
  "readings_count": 1342,
  "series": {
    "billed_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "collected_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "volume_m3": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "readings": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ]
  }
}

Obter o resumo da carteira

Registos

GET /portfolio-overview

Overview totals across the caller's account and its sub-accounts

Builds the business overview for one month for the caller's own account and for every descendant account in its organization tree where the caller holds business:overview:read directly or through an inherited membership; owning the parent alone does not open the children. Each account is returned with its own overview, and billed, collected, volume and reading totals and daily series are summed across them. As in the single-account overview, each data group of each account is shown only when the caller holds that domain's read scope on that account (invoices:read, payments:read, collections:read, business:readings:read, business:consumptions:read, operations:read, support:read). Requires business:overview:read on the caller's tenant. A period that is not YYYY-MM returns 400, and accounts that report in different currencies return 409.

Parâmetros

periodstring · consulta · opcional

Month to report as YYYY-MM, in UTC; defaults to the current month.

Devolve

200 Portfolio overview

Mostrar atributos
root_account_idstring · obrigatório

The caller's tenant, at the root of the portfolio.

periodobject · obrigatório

Reporting month.

Mostrar atributos filhos
labelstring · opcional
startstring (date-time) · opcional
endstring (date-time) · opcional
currencystring · obrigatório

Currency shared by every account in the portfolio.

accountsarray of object · obrigatório

The root account first, then each readable descendant account.

Mostrar atributos filhos
account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account. Omitted when unknown.

account_holder_namestring · opcional

Display name of the account holder. Omitted when unknown.

overviewobject · obrigatório

Domain totals and series are returned only when the caller has the corresponding domain read scope. Receivables require invoices:read or collections:read; collection_rate requires both invoices:read and payments:read. Portfolio overviews apply these checks separately to each account.

Mostrar atributos filhos
periodobject · opcional
currencystring · opcional
billed_centsinteger (int64) · opcional
collected_centsinteger (int64) · opcional
volume_m3number · opcional
readings_countinteger · opcional
collection_ratenumber · opcional

Percentage of the period's billed amount collected through payments applied to invoices billed in that period, capped at 100. Payments against earlier invoices are in arrears_collected_cents and do not raise this rate.

collected_current_period_centsinteger (int64) · opcional

Part of collected_cents applied to invoices billed in the period

arrears_collected_centsinteger (int64) · opcional

Part of collected_cents applied to invoices billed in earlier periods, or to no invoice

collections_by_hourobject · opcional

Collections for the utility's local today and yesterday, independent of the requested period

Mostrar atributos filhos
timezonestring · opcional
todayobject · opcional
yesterdayobject · opcional
read_ratenumber · opcional
open_workobject · opcional
Mostrar atributos filhos
incidentsinteger · opcional
ticketsinteger · opcional
work_ordersinteger · opcional
receivables_by_ageingarray of object · opcional
Mostrar atributos filhos
balance_centsinteger · opcional
bucketstring · opcional
invoicesinteger · opcional
seriesobject · opcional
Mostrar atributos filhos
billed_centsarray of SeriesPoint · opcional
collected_centsarray of SeriesPoint · opcional
volume_m3array of SeriesPoint · opcional
readingsarray of SeriesPoint · opcional
billed_centsinteger (int64) · obrigatório

Sum of billed_cents across the accounts.

collected_centsinteger (int64) · obrigatório

Sum of collected_cents across the accounts.

volume_m3number · obrigatório

Sum of volume_m3 across the accounts.

readings_countinteger · obrigatório

Sum of readings_count across the accounts.

seriesobject · obrigatório

Daily series summed across the accounts, oldest first.

Mostrar atributos filhos
billed_centsarray of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
collected_centsarray of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
volume_m3array of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional
readingsarray of SeriesPoint · opcional
Mostrar atributos filhos
datestring (date) · opcional
valuenumber · opcional

Erros 400 · 401 · 403 · 404 · 409

Permissões business:overview:read · Funções: admin, analyst, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/portfolio-overview" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "root_account_id": "roo_202ZxesHbMupdaSf3oITN8C1tiu",
  "period": {
    "label": "2026-10",
    "start": "2026-11-19T09:30:00Z",
    "end": "2026-11-19T09:30:00Z"
  },
  "currency": "MZN",
  "accounts": [
    {
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "overview": {
        "period": {},
        "currency": "MZN",
        "billed_cents": 1,
        "collected_cents": 1,
        "volume_m3": 13.42,
        "readings_count": 1342,
        "collection_rate": 1,
        "collected_current_period_cents": 1,
        "arrears_collected_cents": 1,
        "collections_by_hour": {
          "timezone": "Africa/Maputo",
          "today": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          },
          "yesterday": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          }
        },
        "read_rate": 1,
        "open_work": {
          "incidents": 1,
          "tickets": 1,
          "work_orders": 1
        },
        "receivables_by_ageing": [
          {
            "balance_cents": 125000,
            "bucket": "bucket",
            "invoices": 1
          }
        ],
        "series": {
          "billed_cents": [
            {}
          ],
          "collected_cents": [
            {}
          ],
          "volume_m3": [
            {}
          ],
          "readings": [
            {}
          ]
        }
      }
    }
  ],
  "billed_cents": 1,
  "collected_cents": 1,
  "volume_m3": 13.42,
  "readings_count": 1342,
  "series": {
    "billed_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "collected_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "volume_m3": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "readings": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ]
  }
}