ligbox/ligbox-ops-platform
3
0
Fork 0
Code Issues 421 Pull requests Projects Releases Packages Wiki Activity Actions
ligbox-ops-platform/specs/034-nextcloud-carbonio-vm112-integration/contracts/nextcloud-provisioning-api.md
Ligbox Spec Hub f6cf9f8e1c Add Spec 034 Nextcloud integration with VM112 Carbonio mail. 
Defines hybrid hot/warm storage to expand tenant mail capacity via Nextcloud Hub on proposed VM116.
2026-06-20 22:07:00 +00:00

3.1 KiB
Raw Blame History

Contrato — Nextcloud Provisioning + Desk API (Spec 034)

Versão: 0.1 draft
Auth Nextcloud OCS: Basic (admin app password) ou token de serviço
Auth Desk: Bearer session (RBAC Spec 027)

1. Nextcloud OCS — utilizador (Wizard VM112)

Criar utilizador

POST /ocs/v1.php/cloud/users
Authorization: Basic {admin}:{app_password}
OCS-APIRequest: true
Content-Type: application/x-www-form-urlencoded

userid=admin%40empresa.com.br&password=***&displayName=Admin+Empresa

Resposta 200:

<ocs>
  <meta><status>ok</status></meta>
  <data/>
</ocs>

Definir quota Files

PUT /ocs/v1.php/cloud/users/{userid}
Content-Type: application/x-www-form-urlencoded

key=quota&value=25GB

Apagar utilizador (purge)

DELETE /ocs/v1.php/cloud/users/{userid}

2. Wizard VM112 — evento interno

Após provision OK:

{
  "event": "onboarding.nextcloud.provisioned",
  "domain": "empresa.com.br",
  "email": "admin@empresa.com.br",
  "nextcloud_userid": "admin@empresa.com.br",
  "files_url": "https://files.empresa.com.br",
  "quota_files": "25GB",
  "carbonio_quota_gb": 5,
  "session_id": "uuid"
}

3. Desk API — health

GET /api/v1/nextcloud/health

Roles: super_admin, ops_lead, technician, noc

Resposta 200:

{
  "status": "ok",
  "vm116": {
    "reachable": true,
    "nextcloud_version": "30.0.0",
    "disk_used_pct": 12,
    "url": "https://cloud.ligbox.com.br"
  },
  "carbonio_vm112": {
    "reachable": true,
    "disk_used_pct": 22
  }
}

4. Desk API — status domínio

GET /api/v1/nextcloud/domains/{domain}/status

Roles: super_admin, ops_lead, technician

Resposta 200:

{
  "domain": "empresa.com.br",
  "carbonio": {
    "accounts": 3,
    "domain_quota_gb": 30,
    "domain_used_gb": 8.2,
    "mail_host": "mail.empresa.com.br"
  },
  "nextcloud": {
    "enabled": true,
    "users": 3,
    "files_url": "https://files.empresa.com.br",
    "total_quota_gb": 75,
    "total_used_gb": 12.1
  }
}

5. Desk API — provision manual

POST /api/v1/nextcloud/domains/{domain}/users

Roles: super_admin, ops_lead

Body:

{
  "email": "vendas@empresa.com.br",
  "display_name": "Vendas",
  "quota_files": "25GB",
  "sync_password": true,
  "password": "********"
}

Resposta 201:

{
  "userid": "vendas@empresa.com.br",
  "files_url": "https://files.empresa.com.br",
  "provisioned_at": "2026-06-20T22:00:00Z"
}

6. Erros standard

HTTP code Descrição
404 domain_not_found Domínio não orquestrado VM112
409 user_exists User NC ou Carbonio já existe
502 nextcloud_unreachable VM116 down
503 feature_disabled NEXTCLOUD_INTEGRATION=0

7. Variáveis ambiente (Wizard VM112)

NEXTCLOUD_INTEGRATION=0
NEXTCLOUD_OCS_URL=https://10.10.10.116
NEXTCLOUD_ADMIN_USER=ligbox-provisioner
NEXTCLOUD_ADMIN_APP_PASSWORD=***
NEXTCLOUD_DEFAULT_QUOTA=25GB
NEXTCLOUD_FILES_URL_TEMPLATE=https://files.{domain}
CARBONIO_DEFAULT_QUOTA_GB=5