# 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

```http
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:**

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

### Definir quota Files

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

key=quota&value=25GB
```

### Apagar utilizador (purge)

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

---

## 2. Wizard VM112 — evento interno

Após provision OK:

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

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

**Resposta 201:**

```json
{
  "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)

```env
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
```