PT EN

Automações

URL base: $BUSINESS_API

O objecto

namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional
O objecto
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar automações

Registos

GET /automations

Returns the tenant's automation rules with cursor pagination (limit defaults to 20, at most 100; pass next_cursor as after). Each rule includes its trigger, conditions, actions, status and current version. Requires automations: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

Return only rules in this state: enabled or disabled; omit for both.

um de enabled, disabled

Devolve

200 Rules

Mostrar atributos
dataarray of AutomationRule · opcional
Mostrar atributos filhos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "trigger": {
        "type": "invoice.issued",
        "days": 1,
        "cron": "cron",
        "timezone": "Africa/Maputo",
        "threshold": 1
      },
      "conditions": [
        {
          "field": "field",
          "operator": "eq"
        }
      ],
      "actions": [
        {
          "type": "send_notification",
          "delay_minutes": 1,
          "params": {}
        }
      ],
      "enabled": true,
      "template_key": "template key",
      "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "status": "enabled",
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Criar uma automação

Registos

POST /automations

Create an automation rule. Requires automations:write and the scope of every action.

Validates the name (up to 200 characters), trigger, conditions and actions, checks that owner_role, when set, is a utility role holding every scope the actions need, and stores the rule as version 1. Rules are enabled unless enabled is false. An enabled rule ignores records that already match at creation time unless apply_to_existing is true; schedule rules have no such baseline. Returns 201; 400 for an invalid rule and 403 when the caller lacks a scope an action needs.

Corpo application/json

namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional

Devolve

201 Created rule

Mostrar atributos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

Erros 400 · 403

Permissões automations:write, business:notification-intents:create · Funções: admin, owner

curl -X POST "$BUSINESS_API/automations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key"
}'
Resposta 201
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar modelos de automação

Registos

GET /automations/templates

Ready-made rules (dunning sequence, overdue reminder, missing-reading follow-up, anomaly review, ticket escalation)

Returns the starter templates, each with a key, name, description and a complete rule body in the shape createAutomation accepts. The templates are fixed and editable: post a template's rule as is, or change it first. Requires automations:read.

Devolve

200 Templates, each with a ready-to-submit rule body

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

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

Templates, each with a ready-to-submit rule body

Obter uma automação

Registos

GET /automations/{id}

Returns one automation rule with its trigger, conditions or condition group, actions, status, owner role, rate limit and current version number. Answers 404 when the rule is not in the caller's tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule (prefix aut_).

Devolve

200 Rule

Mostrar atributos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

Erros 404

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Actualizar uma automação

Registos

PATCH /automations/{id}

Update a rule's name, description, trigger, conditions or actions

Applies only the fields present in the body, then validates the whole rule again, including the caller's and owner_role's scopes for every action. Each successful update increments the version and stores an immutable snapshot. When an enabled rule's trigger or conditions change, records that already match the new criteria are recorded as existing so they do not all fire on the next sweep. Returns 400 for an invalid rule, 403 for a missing action scope and 404 for an unknown rule.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to update (prefix aut_).

Corpo application/json

namestring · opcional
descriptionstring · opcional
triggerobject · opcional
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · opcional
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

Devolve

200 Updated rule

Mostrar atributos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

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

curl -X PATCH "$BUSINESS_API/automations/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ]
}'
Resposta 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Eliminar uma automação

Registos

DELETE /automations/{id}

Permanently removes the rule and its list of existing records it was told to skip, answering 204 with no body. Answers 404 when the rule is not in the caller's tenant. Requires automations:write.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to delete (prefix aut_).

Devolve

204 Deleted

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

curl -X DELETE "$BUSINESS_API/automations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Deleted

Activar uma automação

Registos

POST /automations/{id}/enable

By default only records that match after the rule is enabled fire it. Send apply_to_existing true to also fire it for records that already match.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to enable (prefix aut_).

Corpo application/json

apply_to_existingboolean · opcional · predefinição false

Devolve

200 Enabled rule

Mostrar atributos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

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

curl -X POST "$BUSINESS_API/automations/{id}/enable" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "apply_to_existing": false
}'
Resposta 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Contar os registos existentes de uma automação

Registos

GET /automations/{id}/existing-count

Count the records that already match a rule and have never fired it

Counts the records that match the rule's trigger and conditions right now and have never been claimed by a run of the rule. Use it before enabling with apply_to_existing to see how many records would fire at once. Requires automations:read; the count fails above the per-sweep record limit.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to count records for (prefix aut_).

Devolve

200 How many records applying the rule to existing records would hit

Mostrar atributos
rule_idstring · obrigatório
countinteger · obrigatório

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/existing-count" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "count": 1
}

Desactivar uma automação

Registos

POST /automations/{id}/disable

Disable a rule. Waiting runs are cancelled on their next attempt.

Sets the rule to disabled, increments its version and stores a snapshot. The caller needs automations:write and the scope of every action in the rule. Disabling an already disabled rule still succeeds and bumps the version.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to disable (prefix aut_).

Devolve

200 Disabled rule

Mostrar atributos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

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

curl -X POST "$BUSINESS_API/automations/{id}/disable" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Testar uma automação

Registos

POST /automations/{id}/test

Dry run a rule against a chosen record, with no side effects

Loads the record named by record_type and record_id (both required, except for schedule rules), evaluates the trigger and every condition, and plans each action without running it. The result says whether the rule would fire, why not if it would not (trigger mismatch, a failed condition, or the rule being disabled), each condition's outcome, and per action the planned summary, delay-adjusted start time or the reason it would be skipped. Requires only automations:read.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to test (prefix aut_).

Corpo application/json

record_typestring · obrigatório

um de invoice, payment, meter, reading, consumption, ticket, work_order, disconnection_notice, schedule

record_idstring · obrigatório

Devolve

200 What would happen

Mostrar atributos
rule_idstring · opcional
record_typestring · opcional
record_idstring · opcional
subjectobject · opcional
would_fireboolean · opcional
reasonstring · opcional
conditionsarray of object · opcional
actionsarray of AutomationOutcome · opcional
Mostrar atributos filhos
indexinteger · opcional
typestring · opcional
statusstring · opcional

um de pending, succeeded, failed, skipped, would_run

summarystring · opcional
resource_typestring · opcional
resource_idstring · opcional
resultobject · opcional
errorstring · opcional
attemptsinteger · opcional
not_beforestring (date-time) · opcional
finished_atstring (date-time) · opcional

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X POST "$BUSINESS_API/automations/{id}/test" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "record_type": "invoice",
  "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1"
}'
Resposta 200
{
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "record_type": "record type",
  "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1",
  "subject": {},
  "would_fire": true,
  "reason": "Leitura confirmada no local.",
  "conditions": [
    {}
  ],
  "actions": [
    {
      "index": 1,
      "type": "active",
      "status": "pending",
      "summary": "summary",
      "resource_type": "resource type",
      "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
      "result": {},
      "error": "error",
      "attempts": 1,
      "not_before": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Listar execuções de uma automação

Registos

GET /automations/{id}/runs

Returns the runs the rule has started, with cursor pagination (limit defaults to 20, at most 100). Each run reports its subject record, status and per-action outcomes. Answers 404 when the rule is not in the caller's tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule whose runs to list (prefix aut_).

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

statusstring · consulta · opcional

Return only runs in this state: pending, running, waiting, succeeded, failed or cancelled; omit for all.

um de pending, running, waiting, succeeded, failed, cancelled

Devolve

200 Runs, newest first

Mostrar atributos
dataarray of AutomationRun · opcional
Mostrar atributos filhos
idstring · opcional
rule_idstring · opcional
rule_namestring · opcional
trigger_typestring · opcional
record_typestring · opcional
record_idstring · opcional
statusstring · opcional

um de pending, running, waiting, succeeded, failed, cancelled

attemptsinteger · opcional
errorstring · opcional
outcomesarray of AutomationOutcome · opcional
Mostrar atributos filhos
indexinteger · opcional
typestring · opcional
statusstring · opcional

um de pending, succeeded, failed, skipped, would_run

summarystring · opcional
resource_typestring · opcional
resource_idstring · opcional
resultobject · opcional
errorstring · opcional
attemptsinteger · opcional
not_beforestring (date-time) · opcional
finished_atstring (date-time) · opcional
next_attempt_atstring (date-time) · opcional
started_atstring (date-time) · opcional
finished_atstring (date-time) · opcional
created_atstring (date-time) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/runs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "aut_2lVaKhFGGnDyuBTQy3NKQNviCTv",
      "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
      "rule_name": "Ana Matsinhe",
      "trigger_type": "trigger type",
      "record_type": "record type",
      "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1",
      "status": "pending",
      "attempts": 1,
      "error": "error",
      "outcomes": [
        {
          "index": 1,
          "type": "active",
          "status": "pending",
          "summary": "summary",
          "resource_type": "resource type",
          "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
          "result": {},
          "error": "error",
          "attempts": 1,
          "not_before": "2026-11-19T09:30:00Z",
          "finished_at": "2026-11-19T09:30:00Z"
        }
      ],
      "next_attempt_at": "2026-11-19T09:30:00Z",
      "started_at": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Obter uma execução de uma automação

Registos

GET /automations/{id}/runs/{runId}

Returns one run, including the record it fired for and, for each action, its status, scheduled time, summary, created resource and error. Answers 404 when the run does not exist or belongs to a different rule than the one in the path.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule the run belongs to (prefix aut_).

runIdstring · caminho · obrigatório

Identifier of the run to read; it must belong to the rule given in id.

Devolve

200 Run

Mostrar atributos
idstring · opcional
rule_idstring · opcional
rule_namestring · opcional
trigger_typestring · opcional
record_typestring · opcional
record_idstring · opcional
statusstring · opcional

um de pending, running, waiting, succeeded, failed, cancelled

attemptsinteger · opcional
errorstring · opcional
outcomesarray of AutomationOutcome · opcional
Mostrar atributos filhos
indexinteger · opcional
typestring · opcional
statusstring · opcional

um de pending, succeeded, failed, skipped, would_run

summarystring · opcional
resource_typestring · opcional
resource_idstring · opcional
resultobject · opcional
errorstring · opcional
attemptsinteger · opcional
not_beforestring (date-time) · opcional
finished_atstring (date-time) · opcional
next_attempt_atstring (date-time) · opcional
started_atstring (date-time) · opcional
finished_atstring (date-time) · opcional
created_atstring (date-time) · opcional

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/runs/{runId}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "aut_2lVaKhFGGnDyuBTQy3NKQNviCTv",
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "rule_name": "Ana Matsinhe",
  "trigger_type": "trigger type",
  "record_type": "record type",
  "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1",
  "status": "pending",
  "attempts": 1,
  "error": "error",
  "outcomes": [
    {
      "index": 1,
      "type": "active",
      "status": "pending",
      "summary": "summary",
      "resource_type": "resource type",
      "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
      "result": {},
      "error": "error",
      "attempts": 1,
      "not_before": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z"
    }
  ],
  "next_attempt_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "finished_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Listar versões de uma automação

Registos

GET /automations/{id}/versions

Returns every stored snapshot of the rule in ascending version order, each with the name, trigger, conditions, actions, owner role, author and time it was saved. A new version is written on create, update, enable and disable. Answers 404 when the rule is not in the tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule whose versions to list (prefix aut_).

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Versions, oldest first

Mostrar atributos
dataarray of AutomationRule · opcional
Mostrar atributos filhos
namestring · obrigatório
descriptionstring · opcional
triggerobject · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · opcional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · opcional

Five-field cron expression, schedule only

timezonestring · opcional
thresholdinteger · opcional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · opcional
Mostrar atributos filhos
fieldstring · obrigatório

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · obrigatório

um de eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · opcional
actionsarray of AutomationAction · obrigatório
Mostrar atributos filhos
typestring · obrigatório

um de send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · opcional

Minutes after the previous step

paramsobject · opcional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · opcional
template_keystring · opcional
idstring · opcional
tenant_idstring · opcional
statusstring · opcional

um de enabled, disabled

created_bystring · opcional
created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

Erros 404

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/versions" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "trigger": {
        "type": "invoice.issued",
        "days": 1,
        "cron": "cron",
        "timezone": "Africa/Maputo",
        "threshold": 1
      },
      "conditions": [
        {
          "field": "field",
          "operator": "eq"
        }
      ],
      "actions": [
        {
          "type": "send_notification",
          "delay_minutes": 1,
          "params": {}
        }
      ],
      "enabled": true,
      "template_key": "template key",
      "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "status": "enabled",
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Listar simulações de uma automação

Registos

GET /automations/{id}/backtests

Returns every backtest stored for the rule, newest first, with the window, rule version, status, counts of matched records and records that would act, and the per-record results. The list is not paginated. Requires automations:read.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule whose backtests to list (prefix aut_).

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Backtests, newest first

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

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

Backtests, newest first

Simular uma automação num período passado

Registos

POST /automations/{id}/backtests

Dry-run a rule over a past window; posts nothing

Replays the rule's trigger and conditions over records from a past window and stores the result, without running any action. from and to are required, to must be after from, and the window is at most 366 days; limit caps the recorded results (default 100, at most 1000). Schedule rules cannot be backtested (400). The call answers 202 with the finished backtest; a scan error is reported in the backtest as status failed rather than as an HTTP error.

Parâmetros

idstring · caminho · obrigatório

Identifier of the automation rule to backtest (prefix aut_).

Corpo application/json

fromstring (date-time) · obrigatório
tostring (date-time) · obrigatório
limitinteger · opcional

Devolve

202 Backtest result

Erros 400

Permissões automations:read · Funções: admin, analyst, customer_service, finance, operations, owner

curl -X POST "$BUSINESS_API/automations/{id}/backtests" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-11-19T09:30:00Z",
  "to": "2026-11-19T09:30:00Z",
  "limit": 25
}'
Resposta 202

Backtest result