Skip to main content

Open items

Open items (receivables and payables) come from DATEV Connect. MCP returns the synchronised balances and lines. Write tools change only Fyvel status, comments, tags, and status definitions — not DATEV and not external systems (for example Stripe).

Prerequisites

  • DATEV Connect set up for the company
  • Open items for debtors and/or creditors enabled in the DATEV company settings
  • MCP user with permission Open items → View (read) or Manage (write)
Eligibility per company is on list_companies: openItemsEligible, openItemsReceivablesEnabled, openItemsPayablesEnabled, openItemsConnectAvailable.

Tools

Read

  • list_open_items — paginated list (account or document view), filters including kind, due date, tag, and search. Document rows include tags
  • get_open_item — detail for a stableKey, including lines, the document annotation (with tags), the partner annotation, and a short activity log
  • list_open_item_lines — lines of a personal account, by default from the latest fiscal year (max. 500)
  • list_open_item_statuses — status keys and labels in display order (archived keys are rejected on write)

Status definitions (Fyvel only)

  • create_open_item_status — create an active status from a label. The key is slugified from the label and returned
  • update_open_item_status_label — rename an active status. The key stays the same
  • archive_open_item_status — archive an active status. Existing annotations keep the key, and it can no longer be assigned. There is no restore

Write (Fyvel workflow only)

  • upsert_open_item_document_annotation — status, comment, or tags at document level
  • bulk_upsert_open_item_document_annotations — the same fields for up to 500 documents in one call; each document returns its own result
  • upsert_open_item_partner_annotation — partner default status and comment for a personal account. Tags stay on the document
  • clear_open_item_document_annotation — remove the document override (the partner default applies again)

Typical flow

  1. list_companies — check companyUuid and openItemsEligible
  2. Optionally list_accounts — personal-account names for account numbers
  3. list_open_items with itemKind (receivable / payable) and the matching viewMode
  4. If needed, get_open_item with the stableKey from the list
  5. After reconciling with external data, optionally set an annotation (list_open_item_statuses → upsert)

fiscalYearId

Optional in both list tools. For list_open_items with no value: every synchronised fiscal year. For list_open_item_lines with no value: the latest fiscal year that has lines for this personal account. The year that was actually read is in the fiscalYearId field of the response.

Notes on reconciliation

  • The document reference is often in documentField1. The open balance is in openAmount (lists) or in the line amounts in the detail
  • Lists and lines return only open items by default. For cleared items, set isCleared explicitly
  • Annotations belong on the primary document key: stableKey from list_open_items (document view) or primaryStableKey in the detail
  • newComment replaces the displayed comment and also writes an entry to the activity log
  • Tags suit external references (for example Stripe invoice IDs). They are stored on the document annotation only. tags replaces the entire list. Without tags, existing tags stay
  • list_open_items returns each document’s tags in document view. tag is an exact filter: document view keeps those documents, account view keeps accounts that have at least one
  • Free-text search matches document tags. A partner annotation has no tags
  • For many documents, use bulk_upsert_open_item_document_annotations (max. 500 per call). One failed document does not block the rest