## Fetch the providers' customers and map them (tenant:trade:msp:write)

`POST /api/trade/v1/msp/customers/sync`

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

„Jetzt zuordnen“: asks every enabled provider for its end customers – MailStore its instances, Sophos the
accounts of the usage of this and the previous month, Ingram the end customers of its subscriptions (read from
the Cloud Marketplace API when configured) – and records them as provider customers. A customer with a manual
or automatic mapping is left alone. An unmapped one whose customer number masterdata has as an address's
customer number is mapped automatically (`source: auto`); one masterdata finds by name or postal address only
gets a suggestion; every other one stays open (`GET /api/trade/v1/msp/customers/open`) until a person maps it to an
existing address. Nothing is created in masterdata.

The sync runs in the background: the answer is `202` with the running sync; follow it with
`GET /api/trade/v1/msp/customers/sync`. One sync per tenant at a time (`409 sync_running`).

### Responses

- **202** The sync started. (`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** A sync of the tenant runs already (`sync_running`) or MSP billing is off (`msp_disabled`). (`application/json`)

Fields of the 202 answer:

- `error` (string): Why the sync failed.
- `finishedAt` (string (date-time)): When it finished; absent while running.
- `result` (object): Outcome per provider.
  - `mapped` (integer): Customers mapped automatically by their customer number.
  - `open` (integer): Provider customers to clarify after the sync.
  - `providers` (array of object): Outcome per provider.
    - `customers` (integer): Customers the provider listed.
    - `error` (string): Why the provider could not be read.
    - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
- `startedAt` (string (date-time)): When it started.
- `status` (string): Status of the sync (`running`, `succeeded`, `failed`). (one of `none`, `running`, `succeeded`, `failed`)
- `triggeredBy` (string): Who started the sync.

Example 202 answer:

```json
{
  "startedAt": "2026-11-18T13:00:00Z",
  "status": "running",
  "triggeredBy": "anna.weber@muster-it.example"
}
```

### Example request

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