## Get the state of a billing month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/overview`

Module: Trade · operationId: `getMspOverview` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

The active connectors with their planned collection and run, whether the month is complete (every active
connector collected it; only then may invoices be approved), the subscriptions still missing a customer or an
article, the invoice counts and the automatic billing window. `month` defaults to the month the scheduler
bills now.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Overview (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `autoBilling` (object): The automatic billing window of the month.
  - `enabled` (boolean): Automatic billing is on.
  - `from` (string (date-time)): Start of the automatic billing window of the month.
  - `to` (string (date-time)): End of the automatic billing window of the month.
- `blockers` (array of string): German texts naming what keeps the automatic billing from approving the drafts (e.g. "<n> Preisänderung(en) warten auf Freigabe.": open price suggestions, `listMspPriceSuggestions`); empty: nothing.
- `complete` (boolean): Every active connector has collected the month; only then may invoices be approved.
- `connectors` (array of object): The active connectors in their order.
  - `attempts` (integer): Number of attempts of the run.
  - `error` (string): Why the last run failed.
  - `finishedAt` (string (date-time)): When it finished; absent while running.
  - `itemCount` (integer): Number of usage items collected.
  - `nextAttemptAt` (string (date-time)): When the scheduler tries again.
  - `plannedAt` (string (date-time)): Scheduled collection of the month (in the month after it).
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `runId` (string (uuid)): Id of the usage run.
  - `startedAt` (string (date-time)): When it started.
  - `status` (string): Status of the run of the month. (one of `planned`, `running`, `succeeded`, `failed`)
  - `triggeredBy` (string): `schedule` or the person who collected.
  - `upload` (boolean): The connector's reports are uploaded (`uploadMspItcReport`, ITC Riemer), not collected; `plannedAt` is then zero (`0001-01-01T00:00:00Z`). Missing otherwise.
- `enabled` (boolean): At least one MSP connector is enabled.
- `invoices` (object): Number of MSP invoices of the month per status.
  - `approved` (integer): Number of approved invoices.
  - `drafts` (integer): Number of drafts.
  - `draftsBlocked` (integer): Drafts with problems or still stale.
  - `failed` (integer): Number of failed invoices.
  - `posted` (integer): Number of posted invoices.
- `missingArticle` (integer): Subscriptions (usage items) of the month without an article.
- `missingCustomer` (integer): Subscriptions (usage items) of the month without a customer.
- `month` (integer): Month (1–12) of the billing month.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "autoBilling": {
    "enabled": true,
    "from": "2026-11-05T05:00:00Z",
    "to": "2026-11-10T16:00:00Z"
  },
  "blockers": [
    "1 Abonnement ohne Kunde (Zuordnungen).",
    "1 Preisänderung(en) warten auf Freigabe."
  ],
  "complete": true,
  "connectors": [
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:00:12Z",
      "itemCount": 9,
      "plannedAt": "2026-11-01T05:00:00Z",
      "provider": "mailstore",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f01",
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule"
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-02T05:01:05Z",
      "itemCount": 41,
      "plannedAt": "2026-11-02T05:00:00Z",
      "provider": "sophos",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "startedAt": "2026-11-02T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule"
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:04:31Z",
      "itemCount": 164,
      "plannedAt": "2026-11-01T05:00:00Z",
      "provider": "ingram",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule"
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-03T06:10:02Z",
      "itemCount": 6,
      "plannedAt": "0001-01-01T00:00:00Z",
      "provider": "itc",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f04",
      "startedAt": "2026-11-03T06:10:00Z",
      "status": "succeeded",
      "triggeredBy": "anna.weber@muster-it.example",
      "upload": true
    }
  ],
  "enabled": true,
  "invoices": {
    "approved": 0,
    "drafts": 14,
    "draftsBlocked": 1,
    "failed": 0,
    "posted": 0
  },
  "missingArticle": 0,
  "missingCustomer": 1,
  "month": 10,
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/overview' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
