ConnectCloud Developers

Match an inbound invoice again (tenant:trade:inbound:write)

POST /api/trade/v1/inbound-invoices/{id}/match

Module: Trade · operationId: matchInboundInvoice · Tag: Inbound invoices · Auth: access token (Authorization: Bearer <accessToken>)

Re-runs the purchase order check, optionally against a given purchase order (id or number). Allowed in the same statuses as corrections. The body is optional.

Parameters

Name In Type Required Description
id path string (uuid) yes

Request body

application/json

  • purchaseOrderId (string (uuid))
  • purchaseOrderNumber (string): (max length 64)

Example:

{
  "purchaseOrderNumber": "BE-2026-00058"
}

Responses

  • 200 Matched invoice (application/json)
  • 400 Error (application/json)
  • 401 No valid session or bearer token (no body).
  • 404 Not found in the tenant. (application/json)
  • 409 The current state does not allow the action (code invalid_state or blocked). (application/json)
  • 422 The input is not valid for the stored data. (application/json)
  • 423 An active workflow locks the transaction. (application/json)

Fields of the 200 answer:

  • addressSnapshot (object): The supplier as read (extracted) and as assigned from master data (supplier, assignment), and the VAT ID check of the assigned supplier (vatCheck).
    • assignment (object): How the supplier was assigned (method, confidence, evidence).
    • extracted (object): The supplier as read from the document.
    • supplier (object): The assigned master data supplier.
    • vatCheck (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
      • cached (boolean): The result came from the 24-hour cache of master data.
      • checkedAt (string (date-time)): When the VAT id was checked.
      • method (string): How the VAT id was checked. (one of VIES, BZST)
      • serviceUnavailable (boolean): VIES or the member state could not be reached; check again later.
      • status (string): Outcome of the VAT id check. (one of OFFICIALLY_CONFIRMED, PARTIALLY_CONFIRMED, OFFICIALLY_NOT_CONFIRMED, FORMALLY_VALID_NO_OFFICIAL_CHECK, FORMALLY_INVALID, CHECK_NOT_POSSIBLE, TECHNICAL_ERROR)
      • statusDisplay (string): The status as German text.
      • statusMessage (string): Message of the checking service, if any.
      • vatId (string): VAT id checked.
  • autoRelease (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not off. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
    • eligible (boolean): Every condition holds.
    • evaluatedAt (string (date-time)): When the decision was evaluated.
    • mode (string): Mode of the automatic release when the verdict was made (off, dryRun, on). (one of off, dryRun, on)
    • reasons (array of string): Each failed condition (German text).
    • released (boolean): The system released the invoice (mode on); false again after a reopen.
    • rule (string): The rule that applied, also the protocol note of the release.
    • suppressed (boolean): The release was reopened; the invoice is never released automatically again.
  • createdAt (string (date-time)): When the inbound invoice was created.
  • currency (string): Currency (ISO 4217).
  • customerNo (string): Customer number of the tenant.
  • deliveryDate (string (date)): Delivery date.
  • dmsDocumentId (string (uuid)): DMS document of the invoice.
  • dueDate (string (date)): Due date.
  • duplicateOf (string (uuid)): The invoice this one duplicates (lock reason DUPLIKAT).
  • error (string): Why processing failed (status FAILED).
  • exchangeRate (number): Exchange rate to EUR.
  • extraction (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
    • confidence (object): Per field (AI extraction only).
    • creditorId (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
    • currency (string): Currency (ISO 4217).
    • customerNumber (string): Our customer number at the supplier.
    • deliveryDate (string): Delivery date (YYYY-MM-DD).
    • deliveryNoteNumber (string): Delivery note number stated on the invoice.
    • discountTerms (array of object): Cash discount terms.
      • days (integer): Days within which the discount applies.
      • percent (number): Discount in percent.
    • discountText (string): Cash discount terms as printed.
    • documentType (string): Document type read from the document. (one of 380, 381, 384, 999)
    • documentTypeCode (string): BT-3 code as stated in the e-invoice.
    • dueDate (string): Due date (YYYY-MM-DD).
    • grossTotal (number): Gross total.
    • invoiceDate (string (date)): Invoice date (YYYY-MM-DD).
    • invoiceNumber (string): Invoice number.
    • isReverseCharge (boolean): The invoice is reverse charge.
    • lines (array of InboundInvoiceLine): Lines read from the document.
      • articleAssignment (object): How the article was resolved.
        • confidence (number): Confidence of the article assignment (0–1).
        • evidence (string): What the article assignment is based on.
        • method (string): How the article was found: exact_vat, exact_iban, exact_number, supplier_number, semantic, llm, fallback or manual. (one of exact_vat, exact_iban, exact_number, supplier_number, semantic, llm, fallback, manual)
      • articleNumber (string): Internal article number (masterdata).
      • description (string): Description of the line.
      • ean (string): EAN (GTIN) of the article.
      • ignored (boolean): Article on the configured ignore list.
      • mpn (string): Manufacturer part number.
      • netAmount (number): Net amount of the line.
      • orderLineRef (string): Order line the line refers to (BT-132).
      • orderNumber (string): Order number the line refers to.
      • position (integer): Position number of the line.
      • productId (string): Masterdata article (product) id.
      • quantity (number): Quantity.
      • taxRate (number): Tax rate in percent.
      • unit (string): Unit of measure.
      • unitPrice (number): Net unit price.
      • vendorArticleNo (string): The supplier's article number.
    • mandateReference (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
    • netDays (integer): Days until the net amount is due.
    • netTotal (number): Net total.
    • notes (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
    • orderNumber (string): Order number stated on the invoice.
    • payerIban (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
    • paymentMeansCode (string): Payment means code (BT-81, UNTDID 4461), e.g. 58 SEPA credit transfer, 59 SEPA direct debit; e-invoices only.
    • paymentMeansText (string): Payment means as text (BT-82); e-invoices only.
    • paymentText (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
    • recipient (Party)
      • address (string): Single-line address (e-invoice).
      • city (string): City.
      • country (string): Country.
      • iban (string): IBAN.
      • name (string): Name.
      • street (string): Street and house number.
      • taxNumber (string): Tax number.
      • vatId (string): VAT identification number.
      • zip (string): Postal code.
    • servicePeriodEnd (string (date)): End of the invoiced service period (BT-74); e-invoices only.
    • servicePeriodStart (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
    • sourceKind (string): How it was read (e-invoice XML or OCR and AI extraction). (one of XRECHNUNG_CII, XRECHNUNG_UBL, ZUGFERD, PDF_OCR)
    • taxExemptionReason (string): Stated reason for a tax exemption.
    • taxRates (array of object): Tax breakdown per rate.
      • netAmount (number): Net amount taxed at the rate.
      • rate (number): Tax rate in percent.
      • taxAmount (number): Tax amount at the rate.
    • taxTotal (number): Tax total.
    • vendor (Party)
      • address (string): Single-line address (e-invoice).
      • city (string): City.
      • country (string): Country.
      • iban (string): IBAN.
      • name (string): Name.
      • street (string): Street and house number.
      • taxNumber (string): Tax number.
      • vatId (string): VAT identification number.
      • zip (string): Postal code.
  • fullText (string): OCR text (single invoice only).
  • id (string (uuid)): Id of the inbound invoice.
  • invoiceDate (string (date)): Invoice date.
  • invoiceNumber (string): The supplier's invoice number.
  • lineItems (array of InboundInvoiceLine): Lines of the invoice.
    • articleAssignment (object): How the article was resolved.
      • confidence (number): Confidence of the article assignment (0–1).
      • evidence (string): What the article assignment is based on.
      • method (string): How the article was found: exact_vat, exact_iban, exact_number, supplier_number, semantic, llm, fallback or manual. (one of exact_vat, exact_iban, exact_number, supplier_number, semantic, llm, fallback, manual)
    • articleNumber (string): Internal article number (masterdata).
    • description (string): Description of the line.
    • ean (string): EAN (GTIN) of the article.
    • ignored (boolean): Article on the configured ignore list.
    • mpn (string): Manufacturer part number.
    • netAmount (number): Net amount of the line.
    • orderLineRef (string): Order line the line refers to (BT-132).
    • orderNumber (string): Order number the line refers to.
    • position (integer): Position number of the line.
    • productId (string): Masterdata article (product) id.
    • quantity (number): Quantity.
    • taxRate (number): Tax rate in percent.
    • unit (string): Unit of measure.
    • unitPrice (number): Net unit price.
    • vendorArticleNo (string): The supplier's article number.
  • lockReasons (array of LockReason): Why the invoice may not be released as it is.
    • article (string): Article of the line.
    • code (string): E.g. PREISABWEICHUNG, MENGENABWEICHUNG, DUPLIKAT, FEHLENDER_LIEFERANT, FEHLENDER_ARTIKEL, KEINE_E_RECHNUNG, NIEDRIGE_KONFIDENZ, EMPFAENGER_ABWEICHUNG, LIEFERANT_GESPERRT (the supplier is blocked or payment-blocked in masterdata), FEHLENDE_BESTELLUNG, BESTELLUNG_NICHT_GEFUNDEN, EGIS_ABWEICHUNG (amounts differ from the distributor's invoice data in EGIS).
    • description (string): Human-readable explanation.
    • isBlocking (boolean): The reason blocks the release until it is accepted or overridden.
    • position (integer): Line position the reason refers to; 0 for the whole invoice.
    • variance (number): Variance found (amount or quantity).
  • matchResult (MatchResult)
    • evaluatedAt (string (date-time)): When the match ran.
    • isBlocked (boolean): A blocking lock reason was found.
    • isMatched (boolean): The invoice matches the purchase order within the tolerances.
    • lockReasons (array of LockReason): Lock reasons found.
      • article (string): Article of the line.
      • code (string): E.g. PREISABWEICHUNG, MENGENABWEICHUNG, DUPLIKAT, FEHLENDER_LIEFERANT, FEHLENDER_ARTIKEL, KEINE_E_RECHNUNG, NIEDRIGE_KONFIDENZ, EMPFAENGER_ABWEICHUNG, LIEFERANT_GESPERRT (the supplier is blocked or payment-blocked in masterdata), FEHLENDE_BESTELLUNG, BESTELLUNG_NICHT_GEFUNDEN, EGIS_ABWEICHUNG (amounts differ from the distributor's invoice data in EGIS).
      • description (string): Human-readable explanation.
      • isBlocking (boolean): The reason blocks the release until it is accepted or overridden.
      • position (integer): Line position the reason refers to; 0 for the whole invoice.
      • variance (number): Variance found (amount or quantity).
    • matchedLines (array of object): Result per invoice line.
      • articleNumber (string): Article number in masterdata.
      • availableQty (number): Received minus already invoiced.
      • description (string): Description of the line.
      • invoicePosition (integer): Position on the invoice.
      • invoicedPrice (number): Unit price invoiced.
      • invoicedQty (number): Quantity invoiced.
      • isMatched (boolean): The line matches within the tolerances.
      • poPosition (integer): Position on the purchase order.
      • poPrice (number): Unit price ordered.
      • poQty (number): Quantity ordered.
      • priceVariance (number): Unit price variance.
      • qtyVariance (number): Quantity variance.
      • receivedQty (number): Quantity received.
      • varianceType (string): NONE, PRICE, QUANTITY, BOTH, NOT_RECEIVED or UNKNOWN_POSITION. (one of NONE, PRICE, QUANTITY, BOTH, NOT_RECEIVED, UNKNOWN_POSITION)
    • status (string): matched, variance_detected, blocked, unmatched or not_required. (one of matched, variance_detected, blocked, unmatched, not_required)
    • totalVariance (number): Sum of the price variances.
  • matchingStatus (string): Match status, blocked, or not_applicable for credit notes and corrections.
  • netDays (integer): Days until the net amount is due, as stated (or parsed from the payment text).
  • netTotal (number): Net total.
  • partnerReference (string): Our order number as printed on the invoice.
  • paymentTermsText (string): Payment terms as printed text.
  • processing (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
    • startedAt (string (date-time)): When the current processing started.
    • step (string): queued started, text loading the DMS text, classify and extract the AI service (or reading the e-invoice), evaluate assignments, checks and purchase order match. (one of queued, text, classify, extract, evaluate)
  • purchaseOrderId (string (uuid)): Purchase order the invoice is matched against.
  • resolvedLockReasons (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
    • code (string): Code of the lock reason.
    • comment (string): Why it was accepted.
    • position (integer): Line position the lock reason refers to; 0 for the whole invoice.
    • resolvedAt (string (date-time)): When it was accepted.
    • resolvedBy (string): Who accepted it.
  • skontoDays1 (integer): Days of the first cash discount.
  • skontoDays2 (integer): Days of the second cash discount.
  • skontoRate1 (number): Rate in percent of the first cash discount.
  • skontoRate2 (number): Rate in percent of the second cash discount.
  • skontoTerms (any): Cash discount terms.
  • sourceKind (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of XRECHNUNG_CII, XRECHNUNG_UBL, ZUGFERD, PDF_OCR)
  • status (InboundInvoiceStatus): (one of RECEIVED, OCR_DONE, EXTRACTED, MATCHED, DISCREPANCY, IN_REVIEW, RELEASED, REJECTED, DUPLICATE, FAILED)
  • supplierAddressId (string (uuid)): Masterdata address of the supplier.
  • taxTotal (number): Tax total.
  • tenantName (string): Name of the tenant.
  • totalAmount (number): Gross total of the invoice.
  • totalAmountEur (number): Gross total in EUR (ECB rate).
  • transactionNumber (string): Internal number.
  • transactionType (string): INBOUND_INVOICE or the IN type with the e-invoice code of the document.
  • updatedAt (string (date-time)): When the inbound invoice was last changed.
  • validationReport (object): E-invoice check of the XML, when the invoice is an e-invoice.
  • validationStatus (string): Result of the formal (UStG §14) validation; pending until validated.
  • vendorName (string): Name of the supplier as stated on the invoice.
  • vendorVatId (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "autoRelease": {
    "eligible": false,
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "mode": "dryRun",
    "reasons": [
      "Bruttobetrag 6.911,52 € liegt über der Grenze von 2.500,00 €."
    ],
    "released": false,
    "suppressed": false
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-05T08:41:12Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/match' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"purchaseOrderNumber":"BE-2026-00058"}'

View as Markdown · Interactive reference · OpenAPI