Papierkram MCP by usefulapi

Read the API version and the account's custom invoice templates (ids usable as custom_template_id when creating an invoice).

Takes no parameters.

List contacts (companies: customers and suppliers) with address, VAT id and contact data. Paged.

Get one contact (company) by id, with its people.

List the contact persons of one company. Paged.

Get one contact person of a company.

List outgoing invoices (Ausgangsrechnungen) with state (draft, ...), dates, totals and outstanding_amount. Filter by company, project or document date range. Paged.

Get one outgoing invoice with its line items, billing address and payment term.

List estimates (Angebote) with state, dates and totals. Filter by company, project or document date range. Paged.

Get one estimate with its line items.

List expense vouchers (Belege / incoming invoices and receipts) with creditor, state, dates and amounts. Filter by creditor (supplier company), project or document date range. Paged.

Get one expense voucher with its line items.

List the payment term templates (ids needed as payment_term_id when creating an invoice).

List the stored products and services (Leistungen/Artikel) with article number, price and unit (the VAT rate is only in papierkram_get_proposition). Paged.

Get one stored product or service, including its vat_rate (name such as 19% and rate such as 0.19).

List projects with dates, budget and state. Filter by company. Paged.

Get one project by id.

List time-tracking tasks. Filter by project or product/service. Paged.

Get one task by id.

List tracked time entries. Filter by project, task, invoice, user, billing state or start time range (RFC 3339 date-time). Paged.

Get one time entry by id.

List the bank accounts connected to Papierkram (name, IBAN, balance data as Papierkram reports it). Paged.

List bank transactions (value, currency, usage text, booking date, counterparty). Filter by bank connection. Paged.

Get one bank transaction by id.

List the users of the account (ids needed as user_id for time entries and tasks).

Get one user by id.

WRITE: create a contact (company) in Papierkram. Papierkram assigns the customer number. Nothing is sent to the contact. Check papierkram_list_companies first to avoid duplicates. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: change fields of an existing contact (only the fields you pass are changed). Read it first with papierkram_get_company.

WRITE: add a contact person to an existing company. Nothing is sent to the person. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: create a project for a customer. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: create a time-tracking task in a project. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: record a time entry (worked time) on a task. Not billed until an invoice is made. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: create a stored product or service (Leistung/Artikel) with a price. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: create a DRAFT outgoing invoice (state draft; it is NOT finalized or sent, and gets no invoice number until the user completes it in Papierkram). Needs a payment term id (papierkram_list_payment_terms) and at least one line item. Use papierkram_list_invoices afterwards to check it. Costs Papierkram API credits (a create 10, an invoice or estimate 50; the monthly quota is limited).

WRITE: create a DRAFT estimate (Angebot; state draft, it is NOT finalized or sent, and gets no estimate number until the user completes it in Papierkram). Needs a customer and at least one line item (name, quantity, unit, net unit price, VAT rate). Use papierkram_list_estimates afterwards to check it. Costs 50 Papierkram API credits (the monthly quota is limited).

Get the PDF that Papierkram makes for one expense voucher (GET /expense/vouchers/{id}/pdf). The API reference does not say whether it embeds the uploaded receipt; for the original uploaded file use papierkram_get_voucher_document. Returns the PDF as an embedded file (up to 3 MB).

Get an original file uploaded to an expense voucher (a receipt PDF or image), so its content can be read. Reads the voucher (papierkram_get_voucher) and fetches documents[].uri. Images come back as images, PDFs as an embedded file (up to 3 MB). The API has no documented download for one document: if Papierkram does not serve the file to an API token, the tool says so; then use papierkram_get_voucher_pdf. Files that are not yet attached to a voucher (the upload inbox) are not reachable through the Papierkram API.

WRITE: attach a file (receipt PDF or image) to an existing expense voucher (POST /expense/vouchers/{id}/documents). The file is given as base64, up to 3 MB. Check papierkram_get_voucher first: a repeated upload attaches the file twice. Costs 10 Papierkram API credits.

WRITE: book an expense voucher (Beleg) in Papierkram, e.g. from a receipt. Papierkram books it at once (state unpaid, no draft), so this tool works in two steps. Without confirm it creates nothing: it returns the exact request and possible duplicates (same document date, creditor and total) for the user to review. After the user approves, call again with the same arguments and confirm: true. Then attach the file with papierkram_upload_voucher_document and record a payment with papierkram_pay_voucher. Asset categories that need a depreciation (AfA) setting must be finished in Papierkram. Costs 50 Papierkram API credits; each duplicate check reads 1.

WRITE: book a payment of an expense voucher (POST /expense/vouchers/{id}/pay), with a value and payment date or with an existing bank transaction. Without confirm it changes nothing: it reads the voucher and returns the exact request for the user to review. After approval, call again with confirm: true. A value that differs from the open amount needs difference_reason (teilzahlung = part payment, skonto = cash discount, mahnung = reminder fee, schmaelerung = reduction, sonstige = other). A repeated call books a second payment: after an error, check the voucher state with papierkram_get_voucher before retrying.

WRITE: change an existing expense voucher (PUT /expense/vouchers/{id}): title, supplier, provenance, dates, notes, flag or line items (amount, VAT rate, category). Only the fields you pass are changed. line_items REPLACES all lines of the voucher: pass the full new list. Without confirm it changes nothing: it reads the voucher and returns its current values next to the exact request for the user to review. After approval, call again with the same arguments and confirm: true. Papierkram refuses a voucher that can no longer be edited (e.g. a paid or locked one). Lines with a billing (re-invoicing) or depreciation (AfA) setting cannot be replaced here, so the tool refuses line_items for such a voucher; change those lines in Papierkram. Payments are booked with papierkram_pay_voucher. Costs 1 Papierkram API credit; the preview, and a confirmed line change, also read the voucher (1 each).