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:
{
"articles": 5,
"createdArticles": 2,
"customers": 3,
"replacedArticles": 0
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/auto' \
-H "Authorization: Bearer $ACCESS_TOKEN"