PT EN

Integrações

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · obrigatório
configuration_referencestring · obrigatório

Opaque secret/configuration reference; never a secret value.

statusstring · obrigatório

um de active, suspended, disabled

healthstring · obrigatório

um de unknown, healthy, degraded, unavailable

last_health_check_atstring · opcional · anulável
O objecto
{
  "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142",
  "status": "active",
  "health": "unknown",
  "last_health_check_at": "2026-11-19T09:30:00Z"
}

Listar integrações

Registos

GET /integrations

List external integrations configured for this utility tenant

Returns the integrations registered for the tenant, newest first, with category, provider key, secret configuration reference (never the secret itself), status and last reported health. Results are cursor-paginated (default 20, maximum 100) and the q parameter matches the name case-insensitively; a negative limit returns 400. Requires the business:integrations:read permission.

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.

categorystring · consulta · opcional

Return only integrations of this category: payment, identity, notification, smart_meter, gis, scada, document_store, accounting or erp.

um de payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

statusstring · consulta · opcional

Return only integrations in this status: active, suspended or disabled.

um de active, suspended, disabled

healthstring · consulta · opcional

Return only integrations whose last reported health is unknown, healthy, degraded or unavailable.

um de unknown, healthy, degraded, unavailable

Devolve

200 Tenant-scoped integration registrations

Mostrar atributos
dataarray of Integration · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · obrigatório
configuration_referencestring · obrigatório

Opaque secret/configuration reference; never a secret value.

statusstring · obrigatório

um de active, suspended, disabled

healthstring · obrigatório

um de unknown, healthy, degraded, unavailable

last_health_check_atstring · opcional · anulável
has_moreboolean · obrigatório
next_cursorstring · opcional

Permissões business:integrations:read · Funções: admin, operations, owner

curl -X GET "$BUSINESS_API/integrations" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "name": "Ana Matsinhe",
      "category": "payment",
      "provider_key": "provider key",
      "configuration_reference": "CON-2026-000142",
      "status": "active",
      "health": "unknown",
      "last_health_check_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Registar uma integração

Registos

POST /integrations

Register utility-scoped integration metadata and a config reference

Secret values are kept by the configured secret provider, not stored in this resource.

Corpo application/json

namestring · obrigatório
categorystring · obrigatório

um de payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · obrigatório
configuration_referencestring · obrigatório

Devolve

201 Integration registered

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · obrigatório
configuration_referencestring · obrigatório

Opaque secret/configuration reference; never a secret value.

statusstring · obrigatório

um de active, suspended, disabled

healthstring · obrigatório

um de unknown, healthy, degraded, unavailable

last_health_check_atstring · opcional · anulável

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

curl -X POST "$BUSINESS_API/integrations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142"
}'
Resposta 201
{
  "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142",
  "status": "active",
  "health": "unknown",
  "last_health_check_at": "2026-11-19T09:30:00Z"
}

Obter uma integração

Registos

GET /integrations/{id}

Returns one integration registration with its category, provider key, secret configuration reference, status, health and last health check time. Returns 404 when it is not registered in the tenant. Requires the business:integrations:read permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the integration within the current tenant.

Devolve

200 Integration metadata without provider secrets

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · obrigatório
configuration_referencestring · obrigatório

Opaque secret/configuration reference; never a secret value.

statusstring · obrigatório

um de active, suspended, disabled

healthstring · obrigatório

um de unknown, healthy, degraded, unavailable

last_health_check_atstring · opcional · anulável

Permissões business:integrations:read · Funções: admin, operations, owner

curl -X GET "$BUSINESS_API/integrations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142",
  "status": "active",
  "health": "unknown",
  "last_health_check_at": "2026-11-19T09:30:00Z"
}

Alterar o estado de uma integração

Registos

PATCH /integrations/{id}

Sets the integration's status to active, suspended or disabled. Activating requires a configuration reference to be set, otherwise 400, and any other status value also returns 400; 404 for an unknown integration. The handler answers 204 with no body on success. Requires the business:integrations:manage permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the integration whose status changes.

Corpo application/json

statusstring · obrigatório

um de active, suspended, disabled

Devolve

200 Integration status updated

Permissões business:integrations:manage · Funções: admin, owner

curl -X PATCH "$BUSINESS_API/integrations/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Resposta 200

Integration status updated

Actualizar a configuração de uma integração

Registos

PUT /integrations/{id}/configuration

Replace an integration's secret reference and disable it until re-enabled

The secret value is never accepted or returned; only a reference to the configured secret provider is stored.

Parâmetros

idstring · caminho · obrigatório

Identifier of the integration whose secret configuration reference is replaced; after the change it stays disabled until its status is set back to active.

Corpo application/json

configuration_referencestring · obrigatório

Devolve

204 Configuration updated; integration is disabled until explicitly enabled

Permissões business:integrations:manage · Funções: admin, owner

curl -X PUT "$BUSINESS_API/integrations/{id}/configuration" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "configuration_reference": "CON-2026-000142"
}'
Resposta 204

Configuration updated; integration is disabled until explicitly enabled