PT EN

Subscrição

URL base: $BUSINESS_API

O objecto

plan_codestring · obrigatório
active_connectionsinteger · obrigatório

Connections in status active

max_connectionsinteger · obrigatório

Plan limit; 0 means none

usersinteger · obrigatório

Active team members

max_usersinteger · obrigatório

Plan limit; 0 means none

Obter a subscrição

Registos

GET /subscription

Get utility's active platform SaaS subscription and entitlements

Returns the tenant's platform subscription: its plan ID, status (for example trialing, active, past_due, suspended or cancelled), current billing period, trial end, and whether it is set to cancel at the period end. Plan limits are not embedded; read them from the plan the plan_id points to. Returns 404 when the tenant has no subscription; requires business:subscription:read.

Devolve

200 Active subscription and entitlement limits

Erros 403 · 404

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

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

Active subscription and entitlement limits

Cancelar a subscrição

Registos

POST /subscription/cancel

With at_period_end set to true the subscription keeps running and is only flagged to cancel when the current period ends; with it false or omitted the subscription is cancelled at once. The body is optional and returns the updated subscription. The call does not check the current status, so repeating it is harmless; requires business:subscription:cancel.

Devolve

200 Cancellation recorded

Erros 403 · 404

Permissões business:subscription:cancel · Funções: admin, owner

curl -X POST "$BUSINESS_API/subscription/cancel" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Cancellation recorded

Obter a utilização do plano

Registos

GET /subscription/usage

Returns the tenant's plan code, its active connections and users, and the plan's limits on both. Active connections are those in status active, the same count billing and the connection limit use; a limit of 0 means none. Returns 404 when the tenant has no subscription. Requires business:subscription:read.

Devolve

200 Usage against the plan

Mostrar atributos
plan_codestring · obrigatório
active_connectionsinteger · obrigatório

Connections in status active

max_connectionsinteger · obrigatório

Plan limit; 0 means none

usersinteger · obrigatório

Active team members

max_usersinteger · obrigatório

Plan limit; 0 means none

Erros 404

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/usage" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "plan_code": "C100",
  "active_connections": 87,
  "max_connections": 100,
  "users": 3,
  "max_users": 0
}

Obter os créditos da subscrição

Registos

GET /subscription/credits

Returns every platform credit grant the tenant has received, together with balances in minor units. Only active, unexpired grants with something left count toward the balances, which are split into cash-funded and granted (promotional) credit plus their total. Requires business:billing:read.

Devolve

200 Platform credit summary

Permissões business:billing:read · Funções: admin, finance, owner

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

Platform credit summary

Usar um código promocional

Registos

POST /subscription/credits/redeem

Looks up the campaign behind the code and creates a promotional credit grant for the tenant for the campaign's amount, expiring after the campaign's grant period when it sets one. The new credit is applied right away to the tenant's open platform invoices, and the grant is returned with 201. Returns 404 for an unknown code, 409 when the campaign is not active, its budget or redemption cap is used up, or the tenant has reached its per-tenant limit, and 400 when code is empty; requires business:billing:write.

Devolve

201 Platform credit granted

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

curl -X POST "$BUSINESS_API/subscription/credits/redeem" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Resposta 201

Platform credit granted

Listar facturas da subscrição

Registos

GET /subscription/invoices

Returns the invoices the platform has issued to the caller's tenant for its subscription, in cursor pages (limit up to 100, 20 by default, with after for the next page). Requires business:subscription:read.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

statusstring · consulta · opcional

Returns only invoices in this status: open, paid or void; omit it for all invoices.

um de open, paid, void

Devolve

200 Invoices

Mostrar atributos
dataarray of PlatformInvoice · opcional
Mostrar atributos filhos
payment_methodsarray of string · opcional

The payment methods the platform accepts for this invoice; recording or proving a payment by any other is refused with payment.method_not_configured.

idstring · opcional
tenant_idstring · opcional
organization_idstring · opcional
subscription_idstring · opcional
numberstring · opcional
plan_idstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
linesarray of PlatformInvoiceLine · opcional
Mostrar atributos filhos
codestring · opcional

Stable line code: plan, account_plan, overage_connections, overage_users, proration. Clients word it with params and fall back to description.

descriptionstring · opcional
paramsobject · opcional

Values the code's wording fills in: plan; plan, account, pro_rata; over, included (account, pro_rata); from, to.

tenant_idstring · opcional

Account covered by this line

plan_idstring · opcional

Plan applied to this account

quantitynumber · opcional
unit_price_centsinteger · opcional
amount_centsinteger · opcional
total_centsinteger · opcional
balance_centsinteger · opcional
currencystring · opcional
statusstring · opcional

um de open, paid, void

issued_atstring (date-time) · opcional
due_atstring (date-time) · opcional
paid_atstring (date-time) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Erros 403

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/invoices" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "payment_methods": [
        "payment method"
      ],
      "id": "pla_2FBOA71OWNnW0zzkW3NgMb7QEdr",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
      "subscription_id": "sub_2vVmyFDcAD9ag9fGg1XkQfxiYTR",
      "number": "NUM-2026-000142",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "period_start": "2026-11-19T09:30:00Z",
      "period_end": "2026-11-19T09:30:00Z",
      "lines": [
        {
          "code": "COD-2026-000142",
          "description": "Leitura confirmada no local.",
          "params": {
            "key": "value"
          },
          "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
          "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
          "quantity": 1,
          "unit_price_cents": 125000,
          "amount_cents": 125000
        }
      ],
      "total_cents": 125000,
      "balance_cents": 125000,
      "currency": "MZN",
      "status": "open",
      "issued_at": "2026-11-19T09:30:00Z",
      "due_at": "2026-11-19T09:30:00Z",
      "paid_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Obter uma factura da subscrição

Registos

GET /subscription/invoices/{id}

Returns one platform invoice with its lines, totals and status. An invoice that belongs to another tenant answers 404 just like a missing one; requires business:subscription:read.

Parâmetros

idstring · caminho · obrigatório

ID of the platform invoice issued to the caller's tenant.

Devolve

200 Invoice

Mostrar atributos
payment_methodsarray of string · opcional

The payment methods the platform accepts for this invoice; recording or proving a payment by any other is refused with payment.method_not_configured.

idstring · opcional
tenant_idstring · opcional
organization_idstring · opcional
subscription_idstring · opcional
numberstring · opcional
plan_idstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
linesarray of PlatformInvoiceLine · opcional
Mostrar atributos filhos
codestring · opcional

Stable line code: plan, account_plan, overage_connections, overage_users, proration. Clients word it with params and fall back to description.

descriptionstring · opcional
paramsobject · opcional

Values the code's wording fills in: plan; plan, account, pro_rata; over, included (account, pro_rata); from, to.

tenant_idstring · opcional

Account covered by this line

plan_idstring · opcional

Plan applied to this account

quantitynumber · opcional
unit_price_centsinteger · opcional
amount_centsinteger · opcional
total_centsinteger · opcional
balance_centsinteger · opcional
currencystring · opcional
statusstring · opcional

um de open, paid, void

issued_atstring (date-time) · opcional
due_atstring (date-time) · opcional
paid_atstring (date-time) · opcional

Erros 403 · 404

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/invoices/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "payment_methods": [
    "payment method"
  ],
  "id": "pla_2FBOA71OWNnW0zzkW3NgMb7QEdr",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "subscription_id": "sub_2vVmyFDcAD9ag9fGg1XkQfxiYTR",
  "number": "NUM-2026-000142",
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "code": "COD-2026-000142",
      "description": "Leitura confirmada no local.",
      "params": {
        "key": "value"
      },
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "quantity": 1,
      "unit_price_cents": 125000,
      "amount_cents": 125000
    }
  ],
  "total_cents": 125000,
  "balance_cents": 125000,
  "currency": "MZN",
  "status": "open",
  "issued_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "paid_at": "2026-11-19T09:30:00Z"
}

Mudar de plano

Registos

POST /subscription/change-plan

Change plan now, prorating the difference onto the next invoice

Moves the tenant to plan_id immediately and, when the plans differ in price, adds a proration line for the unused part of the current period to the next platform invoice (a credit when moving to a cheaper plan). Trialing subscriptions, or calls after the period has ended, get no proration. Returns 409 when the subscription is cancelled or already on that plan, and 400 when plan_id is missing or the plans use different currencies; requires business:subscription:change.

Corpo application/json

plan_idstring · obrigatório

Devolve

200 Result with proration_cents (positive charges, negative credits)

Mostrar atributos
subscriptionobject · opcional
from_plan_idstring · opcional
to_plan_idstring · opcional
proration_centsinteger · opcional

Erros 400 · 403 · 404 · 409

Permissões business:subscription:change · Funções: admin, owner

curl -X POST "$BUSINESS_API/subscription/change-plan" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D"
}'
Resposta 200
{
  "subscription": {},
  "from_plan_id": "fro_2oCrPw0hXcafj8kPpsolZgmxtIE",
  "to_plan_id": "top_2Dj6KFZoEjTcgDPWWbViOp9uE1H",
  "proration_cents": 1
}

Pré-visualizar uma mudança de plano

Registos

POST /subscription/change-plan/preview

Runs the same checks and proration calculation as a plan change and returns the from and to plan IDs, the proration amount in cents, the currency and the current period end, without changing the subscription or adding any invoice line. It fails the same way as the real change: 409 for a cancelled subscription or the current plan, 400 for a missing plan_id or a currency mismatch. Requires business:subscription:change.

Corpo application/json

plan_idstring · obrigatório

Devolve

200 Preview with proration_cents (positive charges, negative credits)

Mostrar atributos
from_plan_idstring · opcional
to_plan_idstring · opcional
proration_centsinteger · opcional

Positive charges and negative credits on the next invoice

currencystring · opcional
current_period_endstring (date-time) · opcional

Erros 400 · 403 · 404 · 409

Permissões business:subscription:change · Funções: admin, owner

curl -X POST "$BUSINESS_API/subscription/change-plan/preview" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D"
}'
Resposta 200
{
  "from_plan_id": "fro_2oCrPw0hXcafj8kPpsolZgmxtIE",
  "to_plan_id": "top_2Dj6KFZoEjTcgDPWWbViOp9uE1H",
  "proration_cents": 1,
  "currency": "MZN",
  "current_period_end": "2026-11-19T09:30:00Z"
}

Obter as instruções de pagamento

Registos

GET /subscription/payment-instructions

How to pay platform subscription invoices: bank accounts and mobile-money codes

Returns, in a data array, the payment instructions configured by the platform operator (for example account numbers or payment codes) that a tenant uses to pay its platform invoices. The list is empty when none are configured. Requires business:subscription:read.

Devolve

200 OK

Erros 403

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/payment-instructions" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

OK

Enviar um comprovativo de pagamento da subscrição

Registos

POST /subscription/invoices/{id}/payment-proofs

Send a proof of paying a platform subscription invoice (multipart: amount_cents, method, reference, paid_on, note, file)

Accepts a multipart form with the payment details and a file (PDF, JPEG or PNG) and stores a pending proof for the platform's billing staff to review. The invoice must belong to the tenant and be open (409 otherwise); amount_cents must be positive, method must be one of the payment methods enabled on the installation, reference is required (up to 128 characters), paid_on is a YYYY-MM-DD date not in the future, and note is limited to 500 characters. A second open proof with the same method and reference is rejected with 409; callers need business:subscription:change or payments:write.

Devolve

201 Created; the proof waits for platform review

Erros 409

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

curl -X POST "$BUSINESS_API/subscription/invoices/{id}/payment-proofs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 201

Created; the proof waits for platform review

Listar comprovativos de pagamento da subscrição

Registos

GET /subscription/payment-proofs

Returns the proofs of payment the caller's tenant has sent for its platform invoices, with their review status, in cursor pages (limit up to 100, 20 by default, after for the next page). Requires business:subscription:read.

Parâmetros

invoice_idstring · consulta · opcional

Returns only proofs sent for this platform invoice ID.

statusstring · consulta · opcional

Returns only proofs in this review status: pending, approved or rejected.

um de pending, approved, rejected

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 OK

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/payment-proofs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

OK

Descarregar um comprovativo de pagamento da subscrição

Registos

GET /subscription/payment-proofs/{id}/file

Streams the file attached to a proof with its stored content type and an inline Content-Disposition carrying the original file name. Returns 404 when the proof belongs to another tenant or its file is no longer in storage; requires business:subscription:read.

Devolve

200 The stored PDF, JPEG or PNG

Permissões business:subscription:read · Funções: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/payment-proofs/{id}/file" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

The stored PDF, JPEG or PNG