Zum Inhalt springen

Gutschriften

10 Werkzeuge in dieser Gruppe, jedes mit Stufe, Eigenschaften, Beschreibung und Argumenten.

Die Beschreibung für das Modell und die Argumente stehen auf Englisch, so wie das Modell sie liest.

sevdesk_credit_note_book_payment 

Zahlung auf Gutschrift buchen

Buchenchanges statedestructivesupports dryRunasks the user to confirm

Bucht eine Auszahlung auf eine Gutschrift und verknüpft sie mit dem Kontoumsatz, wenn es einen gibt.

Für das Modell, auf Englisch

Book a payout on a credit note (Gutschrift auszahlen, Zahlungsausgang): amount (gross, positive; sent to sevDesk as money out), date (default today), check account (Zahlungskonto, sevdesk_bank_accounts_list) and, for an imported bank payment, its transactionId (sevdesk_transactions_list, status created) so the transaction is linked instead of counted twice. Bank accounts fed by imports need it. Refuses more than the open amount unless paymentType other_difference says the extra is intended. Open credit notes only (sevDesk reports no paid amount for partially paid ones). Commit tier: asks a human to confirm the preview; dryRun only previews. Undo: sevdesk_credit_note_reset to open.

iderforderlichinteger
Credit note id (not the credit note number), e.g. from sevdesk_credit_notes_list.
amounterforderlichstring | number
Amount paid out, gross, positive, in the credit note's currency, e.g. "119.00" (at most 2 decimals).
dateoptionalstring
Booking date (Zahlungsdatum), YYYY-MM-DD; defaults to today (Berlin).
checkAccountIderforderlichinteger
Check account (Zahlungskonto) the money moved on, from sevdesk_bank_accounts_list.
transactionIdoptionalinteger
Imported bank transaction (Umsatz) to link, from sevdesk_transactions_list (status created, same account). Without it sevDesk creates a new transaction (offline and cash accounts only).
paymentTypeoptionalpayment | cash_discount | bank_fees | other_difference
payment (default): all of the open amount or a part of it. cash_discount: less than the open amount, the rest is written off as Skonto. bank_fees: less, the rest written off as bank fees (Geldverkehrskosten). other_difference: more or less than the open amount for another reason; the document is settled.
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_note_create_draft 

Gutschriftsentwurf anlegen

Entwerfenchanges statesupports dryRun

Legt einen Gutschriftsentwurf mit Positionen an. Versendet oder gebucht wird nichts.

Für das Modell, auf Englisch

Create a draft credit note (Gutschrift) for a contact with its positions. Tier write: it only creates a draft; nothing is sent or booked. Saving reserves the next number of sevDesk's number range (shown in the preview). bookingCategory is required: underachievement (Minderleistung) reduces a finalized invoice of the same contact given as sourceInvoiceId (not cancelled; refused when a credit note for it exists unless allowDuplicate), and every rate must be one of that invoice's rates; provision (Provisionsgutschrift) uses tax rule 9; royalty_assigned/_unassigned (Lizenzen) are not verified live yet. To credit a whole invoice use sevdesk_credit_note_create_from_invoice instead. Defaults: today, net prices, EUR (or the invoice's currency), the contact's invoice address, the account's only user as contact person, tax rule 1 (11 on a Kleinunternehmer account). dryRun previews without saving. After: sevdesk_credit_note_pdf, sevdesk_credit_note_finalize.

contactIderforderlichinteger
Customer contact id (Kontakt), from sevdesk_contacts_search.
bookingCategoryerforderlichunderachievement | provision | royalty_assigned | royalty_unassigned
Buchungskategorie: underachievement (Minderleistung: reduces an issued invoice, needs sourceInvoiceId), provision (Provisionsgutschrift, tax rule 9), royalty_assigned or royalty_unassigned (Lizenzgebühren).
sourceInvoiceIdoptionalinteger
underachievement only: id of the finalized invoice this credit note reduces (refSrcInvoice).
allowDuplicateoptionalboolean
underachievement only: create it even though a credit note for the source invoice exists (e.g. a second partial refund). Default false.
positionserforderlichobject[]
Positionen in printed order; prices per priceMode.
dateoptionalstring
Gutschriftsdatum, YYYY-MM-DD; default today (Europe/Berlin).
deliveryDateoptionalstring
Delivery or service date (Liefer-/Leistungsdatum), YYYY-MM-DD; default the document date.
deliveryDateUntiloptionalstring
End of the delivery period (Leistungszeitraum bis), YYYY-MM-DD.
priceModeoptionalnet | gross
Whether position unit prices are net (netto, the default for new drafts) or gross (brutto). Sets sevDesk's showNet.
taxRuleIdoptionalinteger
Tax rule (Steuerregel) id. Default: the source invoice's rule (underachievement), 9 (provision; 10 on a Kleinunternehmer account) or the account's: 1 for regular VAT, 11 for Kleinunternehmer. See sevdesk_reference_lookup kind=tax_rules.
taxTextoptionalstring
Tax note printed on the document; default: the tax rule's German name.
currencyoptionalstring
ISO 4217 code; default EUR or the source invoice's currency.
headeroptionalstring
Document title (Betreff); default "Gutschrift".
headTextoptionalstring
Intro text above the positions (Kopftext); simple HTML allowed.
footTextoptionalstring
Closing text below the positions (Fußtext); simple HTML allowed.
contactPersonIdoptionalinteger
sevDesk user (SevUser) shown as contact person (Ansprechpartner). Required only when the account has several users: sevdesk_reference_lookup kind=users lists them.
addressNameoptionalstring
Recipient name as printed. Address fields replace the matching parts of the contact's invoice address (new drafts) or of the stored address (updates); the rest is kept.
addressStreetoptionalstring
Street and number.
addressZipoptionalstring
Postcode (PLZ).
addressCityoptionalstring
City (Ort).
addressCountryoptionalstring
ISO 3166-1 alpha-2 country code of the address, e.g. DE, AT, CH; default: the country of the address it changes, else DE.
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_note_create_from_invoice 

Gutschrift aus Rechnung erstellen

Entwerfenchanges statesupports dryRun

Macht aus einer fertigen Rechnung einen Gutschriftsentwurf mit allen Positionen, um sie zu korrigieren oder zu erstatten.

Für das Modell, auf Englisch

Create a credit note draft (Gutschrift / Rechnungskorrektur) from a finalized invoice (open, partially paid or paid; not a draft, Storno, Mahnung or Abo template, and not cancelled) with all its positions: the way to correct or refund a paid invoice. For an unpaid invoice that should be voided completely, cancel it instead (sevdesk_invoice_cancel). Refuses when a credit note for the invoice exists (allowDuplicate overrides, e.g. a second partial refund). Tier write. Afterwards sevDesk's credit note counter is moved past the new draft's number (sevDesk does not do that itself). Then check it with sevdesk_credit_note_get and finalize it with sevdesk_credit_note_finalize.

invoiceIderforderlichinteger
Invoice id (not its number), e.g. from sevdesk_invoices_list.
allowDuplicateoptionalboolean
Create it even though a credit note from this invoice exists. Default: false.
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_note_enshrine 

Gutschrift festschreiben

Buchenchanges statedestructivesupports dryRunasks the user to confirm

Schreibt eine fertige Gutschrift nach GoBD fest. Das lässt sich nicht rückgängig machen.

Für das Modell, auf Englisch

Enshrine a credit note (Gutschrift festschreiben, GoBD): lock it permanently so it can never be reset to draft or deleted again. Irreversible. Payments can still be booked. Only finalized credit notes (status open 200 or later) that are not enshrined yet. Commit tier: asks a human to confirm the preview, with an irreversibility warning; dryRun only previews. Before: sevdesk_credit_note_get (check it is final).

iderforderlichinteger
Credit note id (not the credit note number), e.g. from sevdesk_credit_notes_list.
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_note_finalize 

Gutschrift fertigstellen

Buchenchanges statedestructivesupports dryRunasks the user to confirm

Stellt einen Gutschriftsentwurf fertig und bucht ihn. Versendet wird nichts.

Für das Modell, auf Englisch

Finalize a draft credit note (Gutschrift fertigstellen): sevDesk marks it as sent and books it (draft 100 → open 200) under the number the draft carries. Nothing is sent to the customer: sentVia only records how you send it. To email it through sevDesk use sevdesk_credit_note_send_email instead. Commit tier: asks a human to confirm the shown preview; dryRun only previews. Drafts with a number only (sevDesk can fail half-way on a draft without one; sevdesk_credit_note_create_draft assigns one). Next: sevdesk_credit_note_book_payment (Auszahlung buchen), sevdesk_credit_note_enshrine.

iderforderlichinteger
Credit note id (not the credit note number), e.g. from sevdesk_credit_notes_list.
sentViaoptionalpdf_download | post | print | email
How the document is or was sent, recorded as its send type: pdf_download (VPDF, default: PDF downloaded and sent your own way), post (VP, Briefversand), print (VPR, printed and handed over), email (VM, emailed outside sevDesk).
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_note_get 

Gutschrift abrufen

Lesenread-onlyidempotent

Zeigt eine Gutschrift mit Positionen, Summen, Steuerregel und der Rechnung, auf die sie sich bezieht.

Für das Modell, auf Englisch

Get one credit note (Gutschrift) by its sevDesk id with its positions (name, quantity, unit, unit price net/gross, tax rate, sums), totals (net, Umsatzsteuer, gross), tax rule (Steuerregel), booking category, the invoice or voucher it refers to (sourceInvoiceId, sourceVoucherId), recipient address and delivery date. Use it after sevdesk_credit_notes_list; open the source invoice with sevdesk_invoice_get.

iderforderlichinteger
Credit note id (not its number), e.g. from sevdesk_credit_notes_list.

sevdesk_credit_note_pdf 

Gutschrifts-PDF ansehen

Lesenread-onlyidempotent

Zeigt das PDF einer Gutschrift, ohne sie als versendet zu markieren.

Für das Modell, auf Englisch

Get the PDF of a credit note (Gutschrift), e.g. to show, check or forward it. Read-only preview: it is fetched with preventSendBy, so it never marks the credit note as sent (versendet) or changes its status. The result holds the file's metadata and a resource link; the client loads the file itself via resources/read, its content is never put into the text. To save a copy to disk or as a download link use sevdesk_document_save (available with SEVDESK_OUTPUT_DIR or on a remote server). Find the id with the credit note list tools first.

iderforderlichinteger
sevDesk id of the document (not its number such as RE-1001).

sevdesk_credit_note_reset 

Gutschrift zurücksetzen

Buchenchanges statedestructivesupports dryRunasks the user to confirm

Setzt eine Gutschrift einen Schritt zurück: von bezahlt auf offen oder von offen auf Entwurf.

Für das Modell, auf Englisch

Reset a credit note one step back. to "open" (resetToOpen): a paid or partially paid credit note becomes open again and every booked payout is unlinked (bank transactions return to unbooked; no counter-booking). to "draft" (resetToDraft): an open credit note without payouts becomes a draft again; not for enshrined (festgeschrieben) credit notes. For a paid credit note reset to open first, then to draft. Commit tier: asks a human to confirm the preview; dryRun only previews.

iderforderlichinteger
Credit note id (not the credit note number), e.g. from sevdesk_credit_notes_list.
toerforderlichdraft | open
open: unlink all payments of a paid or partially paid document (resetToOpen). draft: turn an open document without payments back into a draft (resetToDraft).
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_note_send_email 

Gutschrift per E-Mail senden

Versendenchanges statedestructivereaches third partiessupports dryRunasks the user to confirm

Schickt eine Gutschrift über sevDesk per E-Mail. Du bestätigst vorher Empfänger, Betreff und Text.

Für das Modell, auf Englisch

Email a credit note (Gutschrift per E-Mail versenden) through sevDesk: sevDesk sends the PDF to the recipients and marks the credit note as sent; a draft is finalized by this and gets its final number (only allowed when the commit tier is enabled too). External tier: the email reaches the customer and cannot be recalled, so a human confirms the preview with every recipient, the subject and the text first; dryRun only previews. Addresses are checked locally; cc/bcc up to 10 each. To only record that you sent it yourself, use sevdesk_credit_note_finalize. Before: sevdesk_credit_note_get, sevdesk_contact_get, sevdesk_credit_note_pdf.

iderforderlichinteger
Credit note id (not the credit note number), e.g. from sevdesk_credit_notes_list.
toerforderlichstring
Recipient (Empfänger): one email address.
ccoptionalstring[]
Cc recipients, up to 10.
bccoptionalstring[]
Bcc recipients, up to 10.
subjecterforderlichstring
Subject (Betreff), one line.
texterforderlichstring
Email text; simple HTML allowed. sevDesk attaches the document itself.
sendCopyToMeoptionalboolean
Also send a copy to the sevDesk user's own address. Defaults to false.
dryRunoptionalboolean
Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.

sevdesk_credit_notes_list 

Gutschriften auflisten

Lesenread-onlyidempotent

Listet Gutschriften mit Nummer, Status, Kontakt, Datum und Beträgen.

Für das Modell, auf Englisch

List credit notes (Gutschriften) with compact rows: number, status, contact, date, net/tax/gross, booking category (e.g. UNDERACHIEVEMENT = Minderleistung, PROVISION) and the invoice they refer to (sourceInvoiceId). Filter by status (draft = Entwurf, open, partially_paid, paid), contactId, exact credit note number (Gutschriftsnummer) and date range. Page with offset = nextOffset while hasMore. Use detail=summary to browse/find. Use sevdesk_credit_note_get for details and positions. The source invoice: sevdesk_invoice_get.

detailoptionalsummary | full
Use summary to browse/find; full (default) or the matching get tool for details. Default: "full".
statusoptionaldraft | open | partially_paid | paid
draft (100), open (200), partially_paid (750) or paid (1000).
contactIdoptionalinteger
Only credit notes of this contact.
numberoptionalstring
Exact credit note number, e.g. 'GU-1000'.
fromoptionalstring
First day to include, YYYY-MM-DD (Berlin time).
tooptionalstring
Last day to include, YYYY-MM-DD (Berlin time).
limitoptionalinteger
Page size, 1–100. Default: 25.
offsetoptionalinteger
Rows to skip, for paging: pass the previous result's nextOffset. Default: 0.