PT EN

Clientes

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
customer_typestring · obrigatório

um de individual, business

categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

display_namestring · obrigatório
tax_numberstring · opcional
emailstring (email) · opcional
phonestring · opcional
statusstring · obrigatório

um de active, suspended, closed

O objecto
{
  "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Matsinhe",
  "tax_number": "TAX-2026-000142",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "status": "active"
}

Descarregar o modelo de importação de clientes

Registos

GET /customers/import/template

Requires business:customers:create. The CSV header the import reads: display_name (required), customer_type (individual or business, default individual), category (residential, commercial, industrial, institutional or government, default residential), phone, email, tax_number.

Devolve

200 The CSV template

Erros 401 · 403

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

The CSV template

Validar uma importação de clientes

Registos

POST /customers/import/dry-run

Parses and validates the CSV (at most 2000 rows and 2 MiB) and returns every row with its normalized data and errors by field; rows that repeat a phone or e-mail of an earlier row are errors. Nothing is written except the dry run itself, which can be confirmed for 24 hours. Requires business:customers:create.

Corpo application/json

csvstring · obrigatório

CSV text with the header display_name[,customer_type,category,phone,email,tax_number]

Devolve

200 The dry run

Mostrar atributos
dry_run_idstring · obrigatório
confirmedboolean · obrigatório
total_rowsinteger · obrigatório
valid_rowsinteger · obrigatório
error_rowsinteger · obrigatório
created_countinteger · obrigatório
expires_atstring (date-time) · obrigatório
rowsarray of object · obrigatório
Mostrar atributos filhos
rowinteger · obrigatório

Line number in the file (the header is line 1)

dataobject · obrigatório
Mostrar atributos filhos
display_namestring · opcional
customer_typestring · opcional

um de individual, business

categorystring · opcional
phonestring · opcional
emailstring · opcional
tax_numberstring · opcional
errorsarray of object · obrigatório
Mostrar atributos filhos
fieldstring · obrigatório

display_name, customer_type, category, phone, email, tax_number or row

reasonstring · obrigatório

um de required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

codestring · obrigatório

um de required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

duplicate_of_rowinteger · opcional

For duplicate_in_file

createdboolean · obrigatório
customer_idstring · opcional

Erros 400 · 401 · 403

curl -X POST "$BUSINESS_API/customers/import/dry-run" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "csv": "csv"
}'
Resposta 200
{
  "dry_run_id": "dry_2JtWoLL8YFXGwxhQOzhO6PpUIfV",
  "confirmed": true,
  "total_rows": 125000,
  "valid_rows": 1,
  "error_rows": 1,
  "created_count": 1,
  "expires_at": "2026-11-19T09:30:00Z",
  "rows": [
    {
      "row": 1,
      "data": {
        "display_name": "Ana Matsinhe",
        "customer_type": "individual",
        "category": "category",
        "phone": "+258841234567",
        "email": "ana.matsinhe@example.org",
        "tax_number": "TAX-2026-000142"
      },
      "errors": [
        {
          "field": "field",
          "reason": "required",
          "code": "required",
          "duplicate_of_row": 1
        }
      ],
      "created": true,
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck"
    }
  ]
}

Confirmar uma importação de clientes

Registos

POST /customers/import

Creates each valid row of the dry run through the customer service, once per idempotency key (body idempotency_key or the Idempotency-Key header): the same key returns the first answer and creates nothing more; another key returns 409. A dry run with no valid rows returns 400; a stale one (over 24 hours) returns 409. A confirm that creates at least one customer completes the utility_real customer_import step. Requires business:customers:create.

Corpo application/json

dry_run_idstring · obrigatório
idempotency_keystring · opcional

Or the Idempotency-Key header

Devolve

200 The confirmation, with the created customer per row

Mostrar atributos
dry_run_idstring · obrigatório
confirmedboolean · obrigatório
total_rowsinteger · obrigatório
valid_rowsinteger · obrigatório
error_rowsinteger · obrigatório
created_countinteger · obrigatório
expires_atstring (date-time) · obrigatório
rowsarray of object · obrigatório
Mostrar atributos filhos
rowinteger · obrigatório

Line number in the file (the header is line 1)

dataobject · obrigatório
Mostrar atributos filhos
display_namestring · opcional
customer_typestring · opcional

um de individual, business

categorystring · opcional
phonestring · opcional
emailstring · opcional
tax_numberstring · opcional
errorsarray of object · obrigatório
Mostrar atributos filhos
fieldstring · obrigatório

display_name, customer_type, category, phone, email, tax_number or row

reasonstring · obrigatório

um de required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

codestring · obrigatório

um de required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

duplicate_of_rowinteger · opcional

For duplicate_in_file

createdboolean · obrigatório
customer_idstring · opcional

Erros 400 · 401 · 403 · 404 · 409

curl -X POST "$BUSINESS_API/customers/import" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run_id": "dry_2JtWoLL8YFXGwxhQOzhO6PpUIfV",
  "idempotency_key": "idempotency key"
}'
Resposta 200
{
  "dry_run_id": "dry_2JtWoLL8YFXGwxhQOzhO6PpUIfV",
  "confirmed": true,
  "total_rows": 125000,
  "valid_rows": 1,
  "error_rows": 1,
  "created_count": 1,
  "expires_at": "2026-11-19T09:30:00Z",
  "rows": [
    {
      "row": 1,
      "data": {
        "display_name": "Ana Matsinhe",
        "customer_type": "individual",
        "category": "category",
        "phone": "+258841234567",
        "email": "ana.matsinhe@example.org",
        "tax_number": "TAX-2026-000142"
      },
      "errors": [
        {
          "field": "field",
          "reason": "required",
          "code": "required",
          "duplicate_of_row": 1
        }
      ],
      "created": true,
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck"
    }
  ]
}

Listar clientes

Registos

GET /customers

List utility customers using resource filters and cursor pagination

Returns the tenant's customers one cursor page at a time; the filters combine. Requires business:customers:read; an invalid limit or cursor returns 400.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

qstring · consulta · opcional

Resource-specific text search.

customer_typestring · consulta · opcional

Return only customers of this type: individual or business.

um de individual, business

categorystring · consulta · opcional

Return only customers in this tariff category: residential, commercial, industrial, institutional or government.

um de residential, commercial, industrial, institutional, government

statusstring · consulta · opcional

Return only customers in this status: active, suspended or closed.

um de active, suspended, closed

Devolve

200 Utility customers in the authenticated tenant

Mostrar atributos
dataarray of Customer · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
customer_typestring · obrigatório

um de individual, business

categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

display_namestring · obrigatório
tax_numberstring · opcional
emailstring (email) · opcional
phonestring · opcional
statusstring · obrigatório

um de active, suspended, closed

has_moreboolean · obrigatório
next_cursorstring · opcional

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

curl -X GET "$BUSINESS_API/customers" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Ana Matsinhe",
      "tax_number": "TAX-2026-000142",
      "email": "ana.matsinhe@example.org",
      "phone": "+258841234567",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Registar um cliente

Registos

POST /customers

Creates a customer in the authenticated tenant with the active status. display_name, a valid customer_type (individual or business) and a valid category are required; tax_number, email and phone are optional and trimmed. Requires business:customers:create; invalid input returns 400. Creating a customer does not create an account or property, which are separate resources.

Corpo application/json

display_namestring · obrigatório
customer_typestring · obrigatório

um de individual, business

categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

phonestring · opcional
emailstring (email) · opcional
tax_numberstring · opcional

Devolve

201 Customer registered

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
customer_typestring · obrigatório

um de individual, business

categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

display_namestring · obrigatório
tax_numberstring · opcional
emailstring (email) · opcional
phonestring · opcional
statusstring · obrigatório

um de active, suspended, closed

Permissões business:customers:create · Funções: admin, customer_service, owner

curl -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Ana Matsinhe",
  "customer_type": "individual",
  "category": "residential",
  "phone": "+258841234567",
  "email": "ana.matsinhe@example.org",
  "tax_number": "TAX-2026-000142"
}'
Resposta 201
{
  "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Matsinhe",
  "tax_number": "TAX-2026-000142",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "status": "active"
}

Obter um cliente

Registos

GET /customers/{id}

Returns one customer with its type, category, contact details and status. Requires business:customers:read; an unknown customer returns 404.

Parâmetros

idstring · caminho · obrigatório

Identifier of the customer in the authenticated tenant.

Devolve

200 Customer resource

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
customer_typestring · obrigatório

um de individual, business

categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

display_namestring · obrigatório
tax_numberstring · opcional
emailstring (email) · opcional
phonestring · opcional
statusstring · obrigatório

um de active, suspended, closed

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

curl -X GET "$BUSINESS_API/customers/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Matsinhe",
  "tax_number": "TAX-2026-000142",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "status": "active"
}

Obter os metadados de um cliente

Registos

GET /customers/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on a customer, as a resource_type, resource_id and metadata object. A customer without metadata returns an empty map. Requires business:metadata:read; returns 404 when the customer does not exist in the tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the customer whose metadata is read (at most 120 characters).

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/customers/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Actualizar os metadados de um cliente

Registos

PUT /customers/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the supplied keys into the customer's existing metadata and returns the full result; keys not in the request stay unchanged. A request may set at most 50 keys, each key at most 40 characters with no square brackets or control characters, and each value at most 500 characters; a resource may hold at most 50 keys in total. Requires business:metadata:write; invalid keys or values return 400 listing each offending field, and an unknown customer returns 404.

Parâmetros

idstring · caminho · obrigatório

Identifier of the customer whose metadata is merged (at most 120 characters).

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

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

curl -X PUT "$BUSINESS_API/customers/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Descarregar o extracto de conta de um cliente

Registos

GET /customers/{id}/statement.pdf

Renders the customer's statement of account for a date range and returns it as an inline application/pdf file. Movements before from are summed into the opening balance, and movements inside the range are listed in date order with debits and credits. Without from and to the range is the last year up to today; dates use YYYY-MM-DD, and a malformed date or from after to returns 400. Returns 403 when the caller may not read the customer's statement and 404 when the customer does not exist.

Parâmetros

idstring · caminho · obrigatório

Customer 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

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

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

PDF document