PT EN

Contas

URL base: $CONSUMER_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

The utility's slug, so a client can brand the account. Omitted when unknown.

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

Present only in consumer responses and lists the authenticated identity's permissions for this account.

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável
O objecto
{
  "id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "tenant_slug": "tenant slug",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "permissions": [
    "account.read"
  ],
  "account_number": "ACC-2026-000142",
  "billing_entity_id": "bil_2lLuuZnocVf6qrPO4rXsSdtAi95",
  "status": "active",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z"
}

Listar contas

Registos

GET /accounts

List accounts explicitly linked to the authenticated consumer

Pages the utility accounts the signed-in person can access through an active membership, across all tenants. Results can be narrowed with the status, customer_id, property_id and q (search) query parameters and use cursor pagination with limit and after.

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 Accounts authorized for this consumer identity

Mostrar atributos
dataarray of Account · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

The utility's slug, so a client can brand the account. Omitted when unknown.

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

Present only in consumer responses and lists the authenticated identity's permissions for this account.

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável
has_moreboolean · obrigatório
next_cursorstring · opcional
curl -X GET "$CONSUMER_API/accounts" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "tenant_slug": "tenant slug",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
      "property_address": "Av. Julius Nyerere 1420, Maputo",
      "permissions": [
        "account.read"
      ],
      "account_number": "ACC-2026-000142",
      "billing_entity_id": "bil_2lLuuZnocVf6qrPO4rXsSdtAi95",
      "status": "active",
      "opened_at": "2026-11-19T09:30:00Z",
      "closed_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Obter uma conta

Registos

GET /accounts/{id}

Get an explicitly linked account in a selected utility tenant

Returns one account the caller holds an active membership on with the account read permission. The tenant is taken from the X-Tenant-ID header or tenant_id query parameter, or worked out from the caller's memberships; 403 is returned when the caller has no access to the account.

Parâmetros

idstring · caminho · obrigatório

Identifier of the account to return; it must be an account the caller is a member of.

tenant_idstring · consulta · obrigatório

Tenant selector only; the service verifies active account membership.

Devolve

200 Account authorized for the authenticated consumer

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

The utility's slug, so a client can brand the account. Omitted when unknown.

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

Present only in consumer responses and lists the authenticated identity's permissions for this account.

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável
curl -X GET "$CONSUMER_API/accounts/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "tenant_slug": "tenant slug",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "permissions": [
    "account.read"
  ],
  "account_number": "ACC-2026-000142",
  "billing_entity_id": "bil_2lLuuZnocVf6qrPO4rXsSdtAi95",
  "status": "active",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z"
}

Deixar de aceder a uma conta

Registos

DELETE /accounts/{id}/membership

Ends the caller's own membership on an account, recorded as left by the person; the caller loses access to the account's invoices, payments and readings immediately. The tenant comes from X-Tenant-ID, the tenant_id query parameter or the caller's memberships, and 403 is returned when none can be resolved. Returns 204 on success.

Parâmetros

idstring · caminho · obrigatório

Identifier of the account the caller wants to leave.

tenant_idstring · consulta · obrigatório

Tenant selector for locating the explicitly linked account.

Devolve

204 Consumer membership revoked

curl -X DELETE "$CONSUMER_API/accounts/{id}/membership" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Consumer membership revoked

Listar delegados de uma conta

Registos

GET /accounts/{id}/delegates

List delegates and pending invitations (holder only)

Each active delegate also carries display_name, masked_phone and masked_email when known.

Parâmetros

idstring · caminho · obrigatório

Resource identifier

tenant_idstring · consulta · opcional

Tenant of the account

Devolve

200 Delegates

Mostrar atributos
dataarray of object · opcional
Mostrar atributos filhos
idstring · opcional
kindstring · opcional

um de membership, invitation

identity_idstring · opcional
recipientstring · opcional
permissionsarray of string · opcional
statusstring · opcional
curl -X GET "$CONSUMER_API/accounts/{id}/delegates" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "del_2cMzlQ4DheeFbSa75gApbM21xYI",
      "kind": "membership",
      "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
      "recipient": "Ana Matsinhe",
      "permissions": [
        "permission"
      ],
      "status": "active"
    }
  ]
}

Convidar um delegado

Registos

POST /accounts/{id}/delegates

Invite a delegate with limited permissions (holder only)

Lets an account holder invite another person by exactly one of phone (at least 9 digits) or email, returning an invitation with a one-time code the invitee redeems through the account-link call. The caller needs the member invite permission on the account; permissions default to account read and invoice read, can only be ones the caller holds, can never include member invite, and always include account read. The invitation expires after expires_in_hours (1 to 720, default 168).

Parâmetros

idstring · caminho · obrigatório

Resource identifier

tenant_idstring · consulta · opcional

Tenant of the account

Corpo application/json

phonestring · opcional
emailstring · opcional
permissionsarray of string · opcional
expires_in_hoursinteger · opcional

Default 168, maximum 720

account_idstring · opcional

Required in bulk requests

Devolve

201 Invitation with code

Mostrar atributos
idstring · opcional
tenant_idstring · opcional
account_idstring · opcional
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

channelstring · opcional

um de phone, email

recipientstring · opcional
permissionsarray of string · opcional
statusstring · opcional

um de pending, accepted, revoked, expired

codestring · opcional

Present only in the creation response, for the staff member who created the invitation; never returned by listings or logged. The code is also delivered to the recipient by e-mail or text message.

expires_atstring (date-time) · opcional
curl -X POST "$CONSUMER_API/accounts/{id}/delegates" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+258841234567",
  "email": "ana.matsinhe@example.org",
  "permissions": [
    "permission"
  ],
  "expires_in_hours": 1,
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP"
}'
Resposta 201
{
  "id": "acc_2ZN2iF5OIjD2mNrQw1HYCxLsgzR",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "channel": "phone",
  "recipient": "Ana Matsinhe",
  "permissions": [
    "permission"
  ],
  "status": "pending",
  "code": "COD-2026-000142",
  "expires_at": "2026-11-19T09:30:00Z"
}

Revogar um delegado

Registos

DELETE /accounts/{id}/delegates/{delegate_id}

Lets an account holder with the member invite permission remove a delegate: an invitation id (ivt_) revokes the pending invitation, and a membership id ends that person's access to the account. The holder cannot revoke their own membership through this call, and an id that belongs to another account returns 404. Returns 204 on success.

Parâmetros

idstring · caminho · obrigatório

Resource identifier

delegate_idstring · caminho · obrigatório

Resource identifier

tenant_idstring · consulta · opcional

Tenant of the account

Devolve

204 Revoked

curl -X DELETE "$CONSUMER_API/accounts/{id}/delegates/{delegate_id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Revoked

Descarregar o extracto de uma conta

Registos

GET /accounts/{id}/statement.pdf

Renders a PDF account statement for an account linked to the caller, covering from and to (YYYY-MM-DD); to defaults to today and from to one year before to. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Returns 400 for a malformed date or from after to, and 403 or 404 when the account is not in the caller's scope.

Parâmetros

idstring · caminho · obrigatório

Account id

layoutstring · consulta · opcional · predefinição a4

Page format. mobile is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.

um de a4, mobile

fromstring (date) · consulta · opcional

Start of the statement (YYYY-MM-DD); defaults to one year before to

tostring (date) · consulta · opcional

End of the statement (YYYY-MM-DD); defaults to today

Devolve

200 PDF document

Erros 403 · 404

curl -X GET "$CONSUMER_API/accounts/{id}/statement.pdf" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

PDF document