## Look up the month's unmapped usage in masterdata (tenant:trade:msp:write)

`POST /api/trade/v1/msp/mappings/auto`

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

Looks up the month's usage items without customer or article in masterdata. Every succeeded run does the same
after it completes; a masterdata failure never fails the run. A mapping a person saved is never changed.

Customer: masterdata's match is found by customer number (`customerHint`), else by exact name; each is
confirmed by an equal postal address when the provider sent one (Sophos: contact address). Else the postal
address alone. If masterdata has the provider's customer number as an address's customer number (rules
`customerNumber`, `customerNumber+address`) the mapping is **automatic** (`source: auto`) and billed like a
manual one; a match by name or postal address only is **suggested** (`source: suggested`) and bills nothing.
Saving a suggestion with `PUT /api/trade/v1/msp/mappings/customers` makes it manual, and the next billing
computation uses it. An earlier automatic mapping or suggestion is updated when masterdata now names another
customer. The address's `adrNr` and `customerNumber` are stored with the mapping.

Ingram end customers are read from the Cloud Marketplace API when its access is configured (`msp.ingram.marketplace*`
of the config): its `attributes.Custom_Account_ID` is our address number, matched first (`matchedBy: adrNr`). Every customer looked up is recorded as a
provider customer; one that is not mapped automatically is listed by `GET /api/trade/v1/msp/customers/open`.
MSP billing never creates a masterdata address.

Article: the one article whose manufacturer part number equals the SKU is mapped (`source: auto`); with two
such articles nothing is mapped. A Microsoft SKU of Ingram is an article per term: its usage SKU carries the
term (`CFQ7TTC0MBMD:0002/P1YM` – P1YM a year billed monthly, P1YA a year billed yearly, P1MM a month billed
monthly, P10YT ten years billed once; a mapping of the bare SKU still applies to every term). It is mapped to the article numbered `MSFT` + the
SKU without `:` + the term (`MSFTCFQ7TTC0MBMD0002P1YM`, `matchedBy: articleNumber`); when masterdata has none and
`msp.ingram.articleUnitCode` and `articleProductGroupId` are set, that article is created (`matchedBy: created`:
Suchbegriff and manufacturer part number the SKU, Kurzbezeichnung the subscription's name with the term
(`Microsoft 365 F1 1YM`), article type `SUBSCRIPTION` billed in advance with the term's months, no serial numbers,
sales price Ingram's `unitPrice`, the Ingram supplier with Ingram's `unitCost` as purchase price and the article
number without `MSFT`). A Sophos SKU no article carries as part number gets the article `SOPH` + the SKU without
`-` + `P1MM` (`SOPHCIXA0UDAC3P1MM`), found by that number or created from the Infinigate catalog with
`msp.sophos.articleUnitCode` and `articleProductGroupId` set (Infinigate's description, list price as sales price,
the supplier with Infinigate's discounted price, Abonnement of one month); a SKU Infinigate does not know gets
none. Every succeeded run does this by itself; this route repeats it for the month. Drafts become
stale when article mappings were added.

### Parameters

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

### Responses

- **200** How many customer mappings (automatic or suggested) were added or changed and how many article mappings were added. (`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`)

Fields of the 200 answer:

- `articles` (integer): Article mappings added.
- `createdArticles` (integer): Microsoft and Sophos articles created in masterdata (mapped too).
- `customers` (integer): Customer suggestions added or changed.
- `replacedArticles` (integer): Part-number fallbacks of Microsoft SKUs and terms (rule manufacturerPartNumberBare) that now point at their own article.

Example 200 answer:

```json
{
  "articles": 5,
  "createdArticles": 2,
  "customers": 3,
  "replacedArticles": 0
}
```

### Example request

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