ConnectCloud Developers

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"

View as Markdown · Interactive reference · OpenAPI