# Contract: Audit API

**Base**: `https://api.ops.ligbox.com.br` (ou LAN `http://10.10.10.122:8080`)

## GET /api/v1/audit/overview

Lista tenants registados com saúde agregada.

### Response 200

```json
{
  "generated_at": "2026-06-08T18:00:00Z",
  "tenants": [
    {
      "tenant_id": 1,
      "name": "VM112 Ligbox Onboard",
      "ip": "10.10.10.112",
      "status": "degraded",
      "score": { "pass": 6, "warn": 1, "fail": 1, "total": 8 },
      "domains_count": 2,
      "last_audit_at": "2026-06-08T17:55:00Z",
      "top_issues": [
        { "domain": "exemplo.com", "check_id": "dns_dkim", "status": "fail", "message": "TXT not found" }
      ]
    }
  ]
}
```

### Status values

`healthy` | `degraded` | `critical` | `unknown`

---

## GET /api/v1/audit/tenants/{tenant_id}/scorecard

**Query**: `domain` (required)

### Response 200

```json
{
  "tenant_id": 1,
  "domain": "exemplo.com",
  "checked_at": "2026-06-08T17:55:00Z",
  "overall_status": "degraded",
  "checks": [
    {
      "check_id": "carbonio",
      "label": "Carbonio domain",
      "status": "pass",
      "message": "Domain exists in Carbonio",
      "evidence": { "exists": true },
      "checked_at": "2026-06-08T17:55:01Z"
    },
    {
      "check_id": "nginx_vhost",
      "label": "carbonio-nginx vhost",
      "status": "pass",
      "message": "Vhost configured for mail.exemplo.com",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:02Z"
    },
    {
      "check_id": "cert_le",
      "label": "Let's Encrypt certificate",
      "status": "warn",
      "message": "Expires in 21 days",
      "evidence": { "expires_at": "2026-06-29T12:00:00Z" },
      "checked_at": "2026-06-08T17:55:03Z"
    },
    {
      "check_id": "dns_mx",
      "label": "MX record",
      "status": "pass",
      "message": "MX points to mail.exemplo.com",
      "evidence": { "records": ["10 mail.exemplo.com"] },
      "checked_at": "2026-06-08T17:55:04Z"
    },
    {
      "check_id": "dns_spf",
      "label": "SPF",
      "status": "pass",
      "message": "SPF record present",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:05Z"
    },
    {
      "check_id": "dns_dkim",
      "label": "DKIM",
      "status": "fail",
      "message": "default._domainkey TXT not found",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:06Z"
    },
    {
      "check_id": "dns_dmarc",
      "label": "DMARC",
      "status": "pass",
      "message": "DMARC record present",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:07Z"
    },
    {
      "check_id": "webmail_http",
      "label": "Webmail HTTPS",
      "status": "pass",
      "message": "HTTP 200",
      "evidence": { "url": "https://mail.exemplo.com/", "status_code": 200 },
      "checked_at": "2026-06-08T17:55:08Z"
    }
  ]
}
```

---

## POST /api/v1/audit/run/{tenant_id}

Trigger manual audit (ops debugging).

**Query**: `domain` (required)

### Response 202

```json
{
  "status": "queued",
  "tenant_id": 1,
  "domain": "exemplo.com"
}
```

---

## Check IDs (canonical)

`carbonio`, `nginx_vhost`, `cert_le`, `dns_mx`, `dns_spf`, `dns_dkim`, `dns_dmarc`, `webmail_http`

## Check status values

`pass` | `warn` | `fail` | `error` | `skip`