## Start collecting the MSP usage of a month (tenant:trade:msp:write)

`POST /api/trade/v1/msp/collect`

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

Claims the run of the month of every enabled provider and answers `202` at once with them as `running`
(`runs[].runId`); the providers are collected in the background, since one may take minutes (Ingram reads
every subscription and waits out its API quota). Follow the outcome with `listMspRuns`. A provider whose run
another collection holds is listed with `errors`. The collection fetches the usage of the month from every
enabled provider (MailStore, Sophos, Ingram – Microsoft CSP is
bought through Ingram; ITC Riemer is uploaded instead, `uploadMspItcReport`), keeps the raw answers in the database (`rawAnswers` of the run) and replaces the provider's items of the month in one
step; a second collection of the same month never duplicates items. After a successful run every item is
published as `trade.usage.recorded` with the run id. A failing provider fails only its run (`runs`, `errors`)
and keeps the items collected before. Year and month come from the body or the query; without them the
previous month (Europe/Berlin) is collected. The scheduler collects the previous month on the first days of
every month by itself. Drafts of the month become stale and must be recomputed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `year` | query | integer |  |  |
| `month` | query | string |  | Month number, or `YYYY-MM`. |

### Request body

`application/json`

- `month` (integer): (max 12)
- `providers` (array of string): Providers to collect (duplicates count once); only their runs are claimed. Empty or missing collects every enabled provider. A name that is not an enabled provider answers `400` with code `provider_not_enabled`.
- `year` (integer)

Example:

```json
{
  "month": 10,
  "providers": [
    "sophos",
    "ingram"
  ],
  "year": 2026
}
```

### Responses

- **202** Collection started; the claimed runs are `running`, `totalItems` is 0 (`application/json`)
- **400** Invalid request or a provider that is not enabled (code `provider_not_enabled`) (`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`)
- **409** The state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 202 answer:

- `errors` (array of string): Providers that failed or whose run another collection holds.
- `month` (integer): Month (1–12) of the billing month.
- `providersRun` (array of string): Providers collected.
- `runs` (array of object): Run of each provider.
  - `error` (string): Why the run failed.
  - `items` (integer): Number of usage items of the run.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `runId` (string (uuid)): Id of the usage run.
  - `status` (string): `running`: another collection of the provider and month is running; nothing was done. (one of `running`, `succeeded`, `failed`)
- `totalItems` (integer): Number of usage items collected.
- `year` (integer): Year of the billing month.

Example 202 answer:

```json
{
  "errors": [],
  "month": 10,
  "providersRun": [
    "sophos",
    "ingram"
  ],
  "runs": [
    {
      "items": 0,
      "provider": "sophos",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "status": "running"
    },
    {
      "items": 0,
      "provider": "ingram",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "status": "running"
    }
  ],
  "totalItems": 0,
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/collect' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"month":10,"providers":["sophos","ingram"],"year":2026}'
```
