BuchhaltungsButler

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add a basic account** Use to register a new bank, cash or credit-card account before importing transactions for it. Not for chart-of-accounts entries. To add a posting account number, use `postingaccounts_create`. Not idempotent: calling twice with the same name creates two accounts. Check `accounts_list` first. v1 offers no way to update or delete an account afterwards. Endpoint: POST /accounts/add

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get all the accounts** Use to list the bank, cash and credit-card accounts that transactions can be booked against, e.g. to resolve an account name to the numeric `account` id the transaction tools expect. Not the chart of accounts. For posting account numbers such as 1200 or 4400, use `postingaccounts_list`. v1 offers no update or delete endpoint for accounts. An account created here can only be listed afterwards. Endpoint: POST /accounts/get

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add comment to transaction or receipt** Add comment to transaction or receipt. NOTE: You have to submit either a transaction_id_by_customer or a receipt_id_by_customer. Use to attach a free-text note to one receipt or one transaction, for example to record why a booking was categorised the way it was. Exactly one of `transaction_id_by_customer` or `receipt_id_by_customer` must be set. v1 offers no endpoint to read, edit or delete comments, so a comment written here can only be seen in the BuchhaltungsButler web app. Endpoint: POST /comments/add

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add cost location** Add a new cost location. Use to create a cost centre before referencing it from a posting. Not idempotent. Check `cost_locations_list` first to avoid a duplicate. Endpoint: POST /cost-locations/add

🔴 DESTRUCTIVE · deletes data: Deletes or cancels a record. Confirm with the user before calling. Receipt deletes are restorable; cost-location deletes are not. Cancelling a posting deletes it if it is not yet fixed, otherwise it books a reversal posting. **delete cost location** Delete a cost location. Use to remove a cost centre that is no longer needed. Permanent. Unlike a deleted receipt there is no restore endpoint, so confirm with the user before calling. Endpoint: POST /cost-locations/delete

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get cost locations** Get cost locations for a specified customer account. The response includes the number of returned rows and an array of cost locations data. NOTE: Each request is limited to 1000 cost locations! Use to list the cost centres available for the `cost_location` fields on the posting tools. Endpoint: POST /cost-locations/get

🟡 WRITE · updates data: Modifies existing master data in place. **update cost location** Update a cost location's name/description. Use to rename an existing cost centre or change its number. Overwrites the fields you send. Read the current record with `cost_locations_list` first if you intend a partial change. Endpoint: POST /cost-locations/update

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create creditor** Create a creditor account. Use to create one or more suppliers. For customers you invoice, use `debtors_create`. Takes one or many: pass an array of creditors in `creditors`. A single record is an array of one. Not idempotent: check `creditors_list` first, since a repeated call creates duplicate suppliers. v1 offers no delete endpoint, so a creditor created here can only be updated afterwards, never removed. Endpoint: POST /settings/add-batch/creditors

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get creditors** Get all creditors Use to list suppliers, for example to resolve a supplier name to the `creditor` id the receipt and posting tools expect. For customers you invoice, use `debtors_list`. Supports `limit` and `offset`; the response reports the total in `rows`, so page until you have seen that many rows. v1 offers no delete endpoint for creditors, so they can only be created, listed and updated. Endpoint: POST /settings/get/creditors

🟡 WRITE · updates data: Modifies existing master data in place. **update creditor** Update a creditor account. Use to change a supplier's address, bank details or payment terms. Overwrites the fields you send. Read the current record with `creditors_list` first if you intend a partial change. Endpoint: POST /settings/update/creditor

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create debtor** Create a debtor account. Use to create one or more customers. For suppliers you buy from, use `creditors_create`. Takes one or many: pass an array of debtors in `debtors`. A single record is an array of one. Not idempotent: check `debtors_list` first. v1 offers no delete endpoint, so a debtor created here can only be updated afterwards, never removed. Endpoint: POST /settings/add-batch/debtors

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get debitors** Get all debitors Use to list customers, for example to resolve a customer name to the `debtor` id the receipt and posting tools expect. For suppliers you buy from, use `creditors_list`. Supports `limit` and `offset`. v1 offers no delete endpoint for debtors, so they can only be created, listed and updated. Endpoint: POST /settings/get/debtors

🟡 WRITE · updates data: Modifies existing master data in place. **update debtor** Update a debtor account. Use to change a customer's address, bank details or customer number. Overwrites the fields you send. Read the current record with `debtors_list` first if you intend a partial change. Endpoint: POST /settings/update/debtor

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create invoice** Add an invoice for the specified customer. Use to issue a final outgoing invoice that is booked immediately. For an invoice that should stay editable, use `invoices_create_draft`. For a structured XML invoice in XRechnung or ZUGFeRD format, use `invoices_create_e_invoice`. Not idempotent: a second call issues a second invoice with a new number. v1 offers no endpoint to list, change or cancel an invoice once created. Endpoint: POST /invoices/create

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create invoice draft** Add an invoice draft for the specified customer. Use to prepare an invoice that a human should review and release in the BuchhaltungsButler web app. A draft is not booked and carries no invoice number. To issue a final invoice directly, use `invoices_create`. v1 offers no endpoint to list, edit or release drafts. Releasing happens in the web app. Endpoint: POST /invoices/create/draft

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create e-invoice** Add an e-invoice for the specified customer. Use when the recipient requires a structured electronic invoice, for example a German public-sector customer expecting XRechnung. For an ordinary PDF invoice, use `invoices_create`. Not idempotent. v1 offers no endpoint to list or cancel an e-invoice once created. Endpoint: POST /invoices/create/e-invoice

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add postingaccount** Create a postingaccount. Use to add an account number to the chart of accounts that the standard chart does not cover. To register a bank or cash account, use `accounts_create`. Not idempotent. v1 offers no delete endpoint, so a posting account created here can only be updated afterwards. Endpoint: POST /settings/add/postingaccount

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get postingaccounts** Get all postingaccounts Use to list the chart of accounts, for example to find the posting account number for office supplies before booking. Not bank accounts. For the bank, cash and credit-card accounts transactions belong to, use `accounts_list`. Supports `limit` and `offset`; a full SKR chart runs to several hundred rows, so page until `rows` is covered or filter instead. v1 offers no delete endpoint for posting accounts. Endpoint: POST /settings/get/postingaccounts

🟡 WRITE · updates data: Modifies existing master data in place. **update postingaccount** Update a postingaccount. Use to rename a posting account or change its properties. Overwrites the fields you send. Read the current record with `postingaccounts_list` first if you intend a partial change. Endpoint: POST /settings/update/postingaccount

🟡 WRITE · links/unlinks records: Creates or removes an assignment between records (e.g. receipt ↔ transaction). Reversible. **assign receipt to free posting** Assign a receipt to a free posting. Use to attach a receipt to a free posting that was booked without one, so the entry has its supporting document. To link a receipt to a bank transaction rather than a posting, use `transactions_assign_receipts`. Endpoint: POST /postings/assign/receipt-to-free-posting

🔴 DESTRUCTIVE · deletes data: Deletes or cancels a record. Confirm with the user before calling. Receipt deletes are restorable; cost-location deletes are not. Cancelling a posting deletes it if it is not yet fixed, otherwise it books a reversal posting. **cancel posting** Cancel a specified posting. Postings that are not fixed are deleted, fixed postings are cancelled by creating a reversal posting. Use to take a booking out of the books entirely. This is stronger than the `postings_unconfirm_*` tools: those keep the posting and only clear its confirmation, this one removes or reverses it. Prefer unconfirming when the goal is to edit and rebook. The effect depends on the posting: one that is not yet fixed is deleted outright, a fixed one stays and is offset by a reversal posting, which leaves two visible entries in the journal. Confirm with the user before calling. Endpoint: POST /postings/cancel

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add receipt posting** Add postings for a specified receipt. Important: Receipt postings are only available if creditor or debtor posting is activated! IMPORTANT: If you add postings to a receipt with foreign currency, you have to get that receipt (/receipts/get/id_by_customer) and find the calculated amount before performing this request. Use to book one or more receipts that already exist in BuchhaltungsButler, splitting each across posting accounts, VAT rates and cost centres. For a journal entry with no receipt behind it, use `postings_create_free`. Takes one or many: pass an array of receipts in `receipts`. A single record is an array of one. The per-receipt arrays (`postingaccounts`, `amounts`, `vats`, `postingtexts`) are positional: index 0 of each describes the same split line, so they must all have the same length. Not idempotent. Reversible with `postings_unconfirm_for_receipt` while the posting is not fixed. Endpoint: POST /postings/add-batch/receipts

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add transaction posting** Add postings for a specified transaction. Use to book one or more bank transactions, splitting each across posting accounts, VAT rates and cost centres. For a journal entry with no bank transaction behind it, use `postings_create_free`. Takes one or many: pass an array of transactions in `transactions`. A single record is an array of one. The per-transaction arrays are positional and must all have the same length. Not idempotent. Reversible with `postings_unconfirm_for_transaction` while the posting is not fixed. Endpoint: POST /postings/add-batch/transactions

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add free posting** Add a free posting. Use to book a debit/credit pair that is not tied to an existing receipt or bank transaction, such as a manual accrual or a correction. If the booking documents a receipt, use `postings_create_for_receipt`. If it settles a bank transaction, use `postings_create_for_transaction`. Takes one or many: pass an array of free postings in `free_postings`. A single record is an array of one. A "free" posting is BuchhaltungsButler's term for a standalone journal entry: you name both sides yourself via `postingaccount_debit` and `postingaccount_credit`. Not idempotent, so a repeated call books the amount twice. A receipt can be attached afterwards with `postings_assign_receipt_to_free`. Endpoint: POST /postings/add-batch/free

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get postings** Get postings for a specified customer account. The response includes the number of returned rows and an array of postings data. NOTE: Each request is limited to 1000 postings! Use to read the booking journal, filtered by date range or posting account. Supports `limit` and `offset`. Ask for a bounded date range rather than paging through a whole financial year. Endpoint: POST /postings/get

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible. **unconfirm receipt posting** Remove postings for a specified receipt by unconfirming them. This will only work if the postings are not fixed. Use to send a receipt posting back to the unconfirmed state so it can be corrected. This keeps the posting and only clears its confirmation. To remove the posting itself, use `postings_cancel`. Only works while the posting is not fixed. Endpoint: POST /postings/unconfirm/receipt

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible. **unconfirm transaction posting** Remove postings for a specified transaction by unconfirming them. This will only work if the postings are not fixed. Use to send a transaction posting back to the unconfirmed state so it can be corrected. This keeps the posting and only clears its confirmation. To remove the posting itself, use `postings_cancel`. Only works while the posting is not fixed. Endpoint: POST /postings/unconfirm/transaction

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible. **unconfirm free posting** Remove a specified free posting by unconfirming it. This will only work if the posting is not fixed. Use to send a free posting back to the unconfirmed state so it can be corrected. This keeps the posting and only clears its confirmation. To remove the posting itself, use `postings_cancel`. Only works while the posting is not fixed. Fixed postings can no longer be unconfirmed. Endpoint: POST /postings/unconfirm/free

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **add a receipt** Add a receipt into the specified customer account. NOTE: Use this endpoint, to add a receipt without a file! Use to record receipts that have no file attached, for example when the document lives in another system. If you have the actual PDF or image, use `receipts_upload` instead so BuchhaltungsButler can read the document and pre-fill its data. Takes one or many: pass an array of receipts in `receipts`. A single record is an array of one. Not idempotent: a repeated call creates duplicate receipts. The response reports per-item success, so a partial failure leaves the successful entries in place. Endpoint: POST /receipts/addBatch

🔴 DESTRUCTIVE · deletes data: Deletes or cancels a record. Confirm with the user before calling. Receipt deletes are restorable; cost-location deletes are not. Cancelling a posting deletes it if it is not yet fixed, otherwise it books a reversal posting. **delete receipt by id_by_customer** Mark a receipt as deleted for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first. Use to remove a receipt that was filed by mistake. Recoverable: `receipts_restore` brings the receipt back. Confirm with the user before calling. Endpoint: POST /receipts/delete/id_by_customer

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get receipt by id_by_customer** Get a single receipt for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first. The response includes an array of receipt data. Use to fetch a single receipt whose id you already have. To search or page through receipts, use `receipts_list`. `id_by_customer` is the per-customer counter shown in the BuchhaltungsButler UI, not a global database id. Endpoint: POST /receipts/get/id_by_customer

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get receipts** Get receipts for a specified customer account. The response includes the number of returned rows and an array of receipts data. Use to search receipts by direction, date range or payment status. To fetch one known receipt, use `receipts_get_by_id`. `list_direction` is required and selects inbound or outbound receipts. Supports `limit` and `offset`; the response reports the total in `rows`. Endpoint: POST /receipts/get

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get all transactions assigned to a specific receipt** Get all transactions assigned to a specific receipt for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first. Use to see which bank transactions are linked to a given receipt, for example to check whether an invoice has been matched to a payment. For the opposite direction, use `transactions_list_assigned_receipts`. Endpoint: POST /receipts/assigned-transactions/get

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible. **restore deleted receipt by id_by_customer** Restore a marked as deleted receipt for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first. Use to bring back a receipt that was deleted with `receipts_delete`. Endpoint: POST /receipts/restore/id_by_customer

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **upload receipt** Upload a receipt into the specified customer account. The receipt will be processed by the BuchhaltungsButler technology. The response includes the filename (without extension) of the receipt as it is stored. Note: max 10 requests per minute Use to send the actual receipt file. BuchhaltungsButler runs document recognition on it and returns the stored filename. To record a receipt without a file, use `receipts_create`. Rate limited to 10 requests per minute. Not idempotent, so uploading the same file twice creates two receipts. Endpoint: POST /receipts/upload

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create bwa report** Triggers the creation of a BWA report ("Betriebswirtschaftliche Auswertung"). The report is generated asynchronously in the background. The response contains the id_by_customer of the created report, which may be used to retrieve it once the generation has been finished. A new report may only be requested once the generation of a previously requested report of the same type has been finished. Use to request a BWA (Betriebswirtschaftliche Auswertung, the German management report). Step one of two. This only triggers generation. To read the finished report, call `reports_get_bwa` afterwards. Runs asynchronously and returns an id, not the report. A new BWA can only be requested once the previous one has finished, and it replaces the previous one. Endpoint: POST /reports/create/bwa

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates. **create sums report** Triggers the creation of a sums report ("Summen- und Saldenliste"). The report is always created for all of the customer's postingaccounts. The report is generated asynchronously in the background. The response contains the id_by_customer of the created report, which may be used to retrieve it once the generation has been finished. A new report may only be requested once the generation of a previously requested report of the same type has been finished. Use to request a sums and balances report (Summen- und Saldenliste). Step one of two. To read the finished report, call `reports_get_sums` afterwards. Runs asynchronously and returns an id. A new report may only be requested once the previous one has finished, and it replaces the previous one. Endpoint: POST /reports/create/sums

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get bwa report** Returns a previously created BWA report ("Betriebswirtschaftliche Auswertung"). Reports are generated asynchronously, so a report is only available once its generation has been finished. Note that creating a new report of the same type replaces the previously created one. Use to read a BWA that `reports_create_bwa` has finished generating. Step two of two. Returns nothing useful until generation has finished. If the report is not ready, wait and retry rather than requesting a new one, since a new request replaces the pending one. Endpoint: POST /reports/get/bwa

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records. **get sums report** Returns a previously created sums report ("Summen- und Saldenliste"). Reports are generated asynchronously, so a report is only available once its generation has been finished. Note that creating a new report of the same type replaces the previously created one. Use to read a sums and balances report that `reports_create_sums` has finished generating. Step two of two. For the individual bookings behind one posting account, use `reports_get_sums_ledger`. Endpoint: POST /reports/get/sums