PT EN

Agendamentos de facturação

URL base: $BUSINESS_API

O objecto

namestring · obrigatório
service_area_idstring · opcional
day_of_monthinteger · obrigatório
due_daysinteger · obrigatório
estimate_missingboolean · opcional
auto_consumptionboolean · opcional · predefinição true
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de active, paused

next_run_atstring (date-time) · opcional
last_run_atstring (date-time) · opcional
last_run_idstring · opcional
last_errorstring · opcional
O objecto
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}

Listar agendamentos de facturação

Registos

GET /billing-schedules

Returns the tenant's billing schedules with cursor pagination (limit defaults to 20, at most 100), optionally filtered by status (active or paused). Each schedule shows its day of month, due days, service area, next run time and next period start. Requires billing_runs:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Schedules

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-schedules" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Schedules

Criar um agendamento de facturação

Registos

POST /billing-schedules

Create a monthly billing schedule for the tenant or one service area

Creates an active schedule that starts a billing run each month on day_of_month (1 to 28), covering the month before that day; holidays in the tenant calendar are skipped when computing next_run_at. due_days must be 0 to 180 and auto_consumption defaults to true. Only one schedule may cover the whole tenant or a given service area, and a tenant-wide schedule excludes area schedules, so an overlap answers 409. Requires billing_runs:write and returns 201.

Corpo application/json

namestring · obrigatório
service_area_idstring · opcional
day_of_monthinteger · obrigatório
due_daysinteger · obrigatório
estimate_missingboolean · opcional
auto_consumptionboolean · opcional · predefinição true

Devolve

201 Schedule

Mostrar atributos
namestring · obrigatório
service_area_idstring · opcional
day_of_monthinteger · obrigatório
due_daysinteger · obrigatório
estimate_missingboolean · opcional
auto_consumptionboolean · opcional · predefinição true
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de active, paused

next_run_atstring (date-time) · opcional
last_run_atstring (date-time) · opcional
last_run_idstring · opcional
last_errorstring · opcional

Erros 409

Permissões billing_runs:write · Funções: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-schedules" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true
}'
Resposta 201
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}

Obter um agendamento de facturação

Registos

GET /billing-schedules/{id}

Returns one billing schedule with its name, service area, day of month, due days, estimate and auto-consumption flags, status, next run time and next period start. Answers 404 when the schedule is not in the caller's tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing schedule (prefix bsc_).

Devolve

200 Schedule

Mostrar atributos
namestring · obrigatório
service_area_idstring · opcional
day_of_monthinteger · obrigatório
due_daysinteger · obrigatório
estimate_missingboolean · opcional
auto_consumptionboolean · opcional · predefinição true
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de active, paused

next_run_atstring (date-time) · opcional
last_run_atstring (date-time) · opcional
last_run_idstring · opcional
last_errorstring · opcional

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-schedules/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}

Actualizar um agendamento de facturação

Registos

PATCH /billing-schedules/{id}

Applies only the fields present in the body; status accepts active or paused, and the same limits as on create apply (day_of_month 1 to 28, due_days 0 to 180). Resuming a paused schedule or changing day_of_month recomputes next_run_at from now, so missed months are not billed retroactively; other edits keep the period already scheduled. Requires billing_runs:write.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing schedule to update (prefix bsc_).

Corpo application/json

namestring · opcional
day_of_monthinteger · opcional
due_daysinteger · opcional
estimate_missingboolean · opcional
auto_consumptionboolean · opcional
statusstring · opcional

um de active, paused

Devolve

200 Schedule

Mostrar atributos
namestring · obrigatório
service_area_idstring · opcional
day_of_monthinteger · obrigatório
due_daysinteger · obrigatório
estimate_missingboolean · opcional
auto_consumptionboolean · opcional · predefinição true
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de active, paused

next_run_atstring (date-time) · opcional
last_run_atstring (date-time) · opcional
last_run_idstring · opcional
last_errorstring · opcional

Permissões billing_runs:write · Funções: admin, finance, owner

curl -X PATCH "$BUSINESS_API/billing-schedules/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "status": "active"
}'
Resposta 200
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}