ConnectCloud Developers

Compute the drafts of a month (tenant:trade:msp:approve)

POST /api/trade/v1/msp/invoices/recompute

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

Builds one draft per customer address from the contract items due in the month and the assigned usage, priced by the article mapping, else the contract's usage item, else the masterdata article. Usage of Ingram subscriptions the month does not bill (due: false in listMspMonthSubscriptions) is left out. The tenant's own masterdata address (customer number = the tenant's customer number) gets no draft. Lines without article or price are problems that block the approval. Invoices past draft are kept; drafts of customers without positions are removed.

Request body

application/json

  • month (integer): (max 12)
  • year (integer)

Example:

{
  "month": 10,
  "year": 2026
}

Responses

  • 200 The invoices of the month after the computation (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:

  • invoices (array of MspInvoice)
    • addressId (string (uuid)): Masterdata address of the customer.
    • addressName (string): Name of the customer.
    • approvedAt (string (date-time)): When the invoice was approved.
    • approvedBy (string): Who approved the invoice.
    • attempts (integer): Number of posting attempts.
    • computedAt (string (date-time)): When the draft was computed.
    • delivery (MspDelivery): send: approving issues the invoice in Verkauf and mails it to the customer; issue: it is only issued (final number, XRechnung, the XML in DMS). (one of send, issue)
    • error (string): Why the last posting failed.
    • id (string (uuid)): Id of the MSP invoice.
    • lines (array of MspInvoiceLine): Positions of the invoice.
      • articleNumber (string): Article number in masterdata.
      • contractId (string (uuid)): Contract of the position.
      • contractItemId (string (uuid)): The contract position of a fixed line.
      • kind (string): fixed (a contract item) or usage (collected usage). (one of fixed, usage)
      • name (string): Name printed on the invoice position.
      • position (integer): Position number of the line.
      • problem (string): Why the position cannot be billed as it is.
      • provider (string): MSP provider (mailstore, sophos, ingram, itc, …).
      • quantity (number): Quantity.
      • sourceSku (string): The provider's SKU.
      • text (string): Printed below the name; missing when none. ITC: VM: <name> of the virtual machine.
      • total (number): Net total of the position.
      • unitPrice (number): Missing when no price is known (a problem).
      • usageItemIds (array of string (uuid)): The usage items of a usage line.
    • month (integer): Month (1–12) of the billing month.
    • netTotal (number): Net total of the invoice.
    • postedAt (string (date-time)): When the invoice was posted.
    • problems (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
    • stale (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
    • status (string): Status of the MSP invoice (draft, approved, posting, posted, failed). (one of draft, approved, posting, posted, failed)
    • transactionId (string (uuid)): The booked INVOICE in trade.
    • transactionNumber (string): Number of the invoice in Verkauf once posted.
    • year (integer): Year of the billing month.
  • month (integer)
  • problems (array of string)
  • unassigned (integer): Number of usage items without customer (listMspUnassignedUsage).
  • year (integer)

Example 200 answer:

{
  "invoices": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
      "lines": [
        {
          "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
          "kind": "usage",
          "name": "Microsoft 365 Business Standard 1YM",
          "position": 1,
          "provider": "ingram",
          "quantity": 12,
          "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
          "total": 150,
          "unitPrice": 12.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
          ]
        },
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 2,
          "provider": "itc",
          "quantity": 4,
          "sourceSku": "7030222",
          "text": "VM: kanzlei-srv01",
          "total": 38,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 3,
          "provider": "itc",
          "quantity": 16,
          "sourceSku": "7030220",
          "text": "VM: kanzlei-srv01",
          "total": 51.2,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 4,
          "provider": "itc",
          "quantity": 500,
          "sourceSku": "7030003",
          "text": "VM: kanzlei-srv01",
          "total": 60,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
          ]
        },
        {
          "articleNumber": "DL-9005",
          "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
          "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
          "kind": "fixed",
          "name": "Supportpauschale Fernwartung, monatlich",
          "position": 5,
          "quantity": 1,
          "total": 180,
          "unitPrice": 180
        }
      ],
      "month": 10,
      "netTotal": 479.2,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressName": "Donau Maschinenbau AG",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
      "lines": [
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 1,
          "provider": "itc",
          "quantity": 8,
          "sourceSku": "7030222",
          "text": "VM: dmb-erp01",
          "total": 76,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c14"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 2,
          "provider": "itc",
          "quantity": 32,
          "sourceSku": "7030220",
          "text": "VM: dmb-erp01",
          "total": 102.4,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c15"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 3,
          "provider": "itc",
          "quantity": 1200,
          "sourceSku": "7030003",
          "text": "VM: dmb-erp01",
          "total": 144,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c16"
          ]
        }
      ],
      "month": 10,
      "netTotal": 322.4,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    }
  ],
  "month": 10,
  "problems": [],
  "unassigned": 1,
  "year": 2026
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/recompute' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"month":10,"year":2026}'

View as Markdown · Interactive reference · OpenAPI