Alle Gutschriften auflisten
GET /api/credit-notes
<?xml version="1.0" encoding="UTF-8"?>
<credit-notes type="array" page="1" per_page="100" total="2">
<credit-note>
...
</credit-note>
<credit-note>
...
</credit-note>
</credit-notes>
Über Parameter kann gefiltert werden:
GET /api/credit-notes?credit-note_number=GS123
Listet alle Gutschriften auf, die „GS123“ in der Gutschriftennummer haben. Groß- und Kleinschreibung wird ignoriert.
Folgende Filter-Parameter stehen zur Verfügung:
Parameter |
Beschreibung |
client_id |
ID des Kunden |
contact_id |
ID des Kontakts |
credit_note_number |
Gutschriftennummer |
status |
Gutschriftenstatus (DRAFT, OPEN, PAID). Mehrere Stati können per Komma getrennt werden. |
from |
Nur Gutschriften ab diesem Datum (Format YYYY-MM-DD) |
to |
Nur Gutschriften bis zu diesem Datum (Format YYYY-MM-DD) |
label |
Freitextsuche in der Bezeichnung |
intro |
Freitextsuche im Einleitungstext |
note |
Freitextsuche im Anmerkungstext |
tags |
Kommaseparierte Liste der Schlagworte |
article_id |
ID eines Artikels, der enthalten ist |
Gutschriften aggregiert auflisten
GET /api/credit-notes?group_by=client
Gutschriften können auch gruppiert abgerufen werden. Obiges Beispiel gruppiert alle Gutschriften nach Kunde.
Folgende Werte stehen für den Parameter group_by zur Verfügung:
Wert |
Beschreibung |
client |
Kunde |
status |
Gutschriftenstatus |
day |
Tag |
week |
Woche (beginnt mit Montag) |
month |
Monat |
year |
Jahr |
Es kann auch nach mehreren Kriterien gruppiert werden. Dabei werden die gewünschten Werte einfach per Komma aneinandergehängt (?group_by=client,year). Die Reihenfolge der Werte bestimmt dabei die Reihenfolge der Aggregation.
Der Gruppierungs-Parameter kann auch mit den restlichen Filtern kombiniert werden.
<?xml version="1.0" encoding="UTF-8"?>
<credit-note-groups type="array" currency_code="USD">
<credit-note-group>
<total_gross type="float">347.28</total_gross>
<total_net type="float">291.83</total_net>
<client_id type="integer">476</client_id>
<credit-note-params>
<client_id type="integer">476</client_id>
</credit-note-params>
</credit-note-group>
<credit-note-group>
<total_gross type="float">1127.53</total_gross>
<total_net type="float">947.50</total_net>
<client_id type="integer">477</client_id>
<credit-note-params>
<client_id type="integer">477</client_id>
</credit-note-params>
</credit-note-group>
</credit-note-groups>
Einzelne Gutschrift aufrufen
GET /api/credit-notes/{id}
<?xml version="1.0" encoding="UTF-8"?>
<credit-note>
<id type="integer">1</id>
<client_id type="integer">123</client_id>
<contact_id type="integer"></contact_id>
<created type="datetime">2007-12-13T12:12:00+01:00</created>
<credit_note_number>GS123</credit_note_number>
<number type="integer">123</number>
<number_pre>RE</number_pre>
<number_length type="integer">0</number_length>
<status>OPEN</status>
<date type="date">2009-10-14</date>
<address>Billomat GmbH &amp;amp; Co. KG
Hollertszug 26
57562 Herdorf
Deutschland</address>
<title></title>
<label>Projekt 123</label>
<intro>Wir schreiben Ihnen folgende Positionen gut:</intro>
<note>Vielen Dank!</note>
<total_gross type="float">107.1</total_gross>
<total_net type="float">90.0</total_net>
<net_gross>NET</net_gross>
<reduction>10</reduction>
<total_gross_unreduced type="float">119.0</total_gross_unreduced>
<total_net_unreduced type="float">100.0</total_net_unreduced>
<currency_code>EUR</currency_code>
<quote type="float">1.0000</quote>
<customerportal_url>https://mybillomatid.billomat.net/customerportal/creditnotes/show/entityId/123?hash=123456789aabbcc</customerportal_url>
<taxes type="array">
<tax>
<name>MwSt</name>
<rate type="float">19.0</rate>
<amount type="float">19.0</amount>
</tax>
</taxes>
<invoice_id></invoice_id>
<template_id></template_id>
</credit-note>
status kann folgende Werte haben:
– DRAFT (Entwurf)
– OPEN (offen)
– PAID (bezahlt)
net_gross kann folgende Werte haben:
– NET (Netto-Preise)
– GROSS (Brutto-Preise)
Zusätzlich zu der eigentlichen Gutschrift werden noch die zusammengefassten Steuern (taxes) mit zurückgegeben.
Die Gutschriftenpositionen, Gutschriftenkommentare und Zahlungen können gesondert abgerufen werden.
Gutschrift erstellen
POST /api/credit-notes
XML-Element |
Beschreibung |
Typ |
Default-Wert |
Pflichtfeld |
client_id |
ID des Kunden |
INT |
|
ja |
contact_id |
ID des Kontakts |
INT |
|
|
address |
komplette Gutschriftenadresse |
ALNUM |
Adresse des Kunden |
|
number_pre |
Präfix |
ALNUM |
Wert aus Einstellungen |
|
number |
lfd. Nummer |
INT |
nächste freie Nummer |
|
number_length |
Mindestlänge der Gutschriftennummer (wird mit führenden Nullen aufgefüllt) |
INT |
Wert aus den Einstellungen |
|
date |
Gutschriftendatum |
DATE |
heute |
|
title |
Dokumentenüberschrift |
ALNUM |
|
|
label |
Bezeichnung |
ALNUM |
|
|
intro |
Einleitungstext |
ALNUM |
Wert aus Einstellungen |
|
note |
Anmerkungstext |
ALNUM |
Wert aus Einstellungen |
|
reduction |
Rabatt (Absolut oder als Prozentwert: 10/10%) |
ALNUM |
|
|
currency_code |
Währung |
ISO-Währungscode |
Standard-Währung |
|
net_gross |
Preisbasis (Brutto- oder Netto-Preise) |
ALNUM („NET“, „GROSS“) |
Wert aus den Einstellungen |
|
quote |
Währungskurs (für Umrechnung in Standard-Währung) |
FLOAT |
1.0000 |
|
invoice_id |
Die ID der Rechnung, wenn die Gutschrift aus einer Rechnung erstellt wurde. |
INT |
|
|
free_text_id |
Die ID des Freitextes zur Belegung von title, label, intro und note. |
INT |
|
|
template_id |
Die ID der Vorlage, mit der die Gutschrift abgeschlossen werden soll. |
INT |
ID der Standardvorlage |
|
status ist bei der Erstellung immer DRAFT.
Die übrigen Eigenschaften der Gutschrift werden automatisch berechnet.
Gutschriftenpositionen (credit-note-items) können bei der Erstellung direkt mit angegeben werden. Es gelten die gleichen XML-Elemente wie unter Gutschriftenposition erstellen. Nur das XML-Element credit_note_id muss nicht mit angegeben werden.
<credit-note>
<client_id>1</client_id>
<date>2009-11-18</date>
<note>Wir schreiben Ihnen gut:</note>
<credit-note-items>
<credit-note-item>
<unit>Stück</unit>
<unit_price>1.23</unit_price>
<quantity>1.5</quantity>
<title>Muster</title>
</credit-note-item>
<credit-note-item>
<unit>Stunde</unit>
<unit_price>90</unit_price>
<quantity>8</quantity>
<title>Arbeiten</title>
</credit-note-item>
</credit-note-items>
</credit-note>
<?xml version="1.0" encoding="UTF-8"?>
<credit-note>
<id type="integer">1234</id>
<client_id type="integer">1</client_id>
<created type="datetime">2007-12-13T12:12:00+01:00</created>
<credit_note_number>RE124</credit_note_number>
<number type="integer">124</number>
<number_pre>RE</number_pre>
<number_length type="integer">0</number_length>
<date type="date">2009-11-18</date>
...
</credit-note>
Gutschrift bearbeiten
PUT /api/credit-notes/{id}
Eine Gutschrift kann grundsätzlich nur im Entwurfs-Status (DRAFT) bearbeitet werden.
Gutschriftenpositionen und Kommentare können nicht direkt über die Gutschrift bearbeitet werden. Bitte dafür über die entsprechende Ressource gehen.
<credit-note>
<date>2009-10-13</date>
</credit-note>
Gutschrift löschen
DELETE /api/credit-notes/{id}
Löscht eine Gutschrift inkl. aller dazugehöriger Dokumente (PDFs), Gutschriftenositionen und Kommentare.
Gutschrift abschließen
PUT /api/credit-notes/{id}/complete
Schließt eine Gutschrift im Entwurfsstatus (DRAFT) ab. Dabei wird der Status auf offen (OPEN) gesetzt, ein PDF erzeugt und im Dateisystem abgelegt.
Welche Vorlage für die PDF-Erzeugung benutzt wird, steuert der optionale Parameter template_id.
Wird dieser Parameter nicht angegeben, wird entweder die an der Gutschrift hinterlegte Vorlage oder die eingestellte Standardvorlage benutzt.
<complete>
<template_id>123</template_id>
</complete>
PDFs einer Gutschrift aufrufen
GET /api/credit-notes/{id}/pdf
Als optionaler Parameter kann type=signed verwendet werden, um das digital signierte PDF aufzurufen.
An dieser Stelle kann außerdem der Parameter format=pdf verwendet werden, um das PDF direkt mit Mimetype „application/pdf“ aufzurufen. Über den optionalen Parameter type=print kann das PDF ohne Hintergrund angefordert werden. Bitte beachte, dass zum Zeitpunkt der Erstellung die Einstellung print_version bei den Settings aktiviert gewesen sein muss.
<pdf>
<id type="integer">4882</id>
<created type="datetime">2009-09-02T12:04:15+02:00</created>
<credit_note_id type="integer">240</credit_note_id>
<filename>credit-note_123.pdf</filename>
<mimetype>application/pdf</mimetype>
<filesize>70137</filesize>
<base64file>{base64-kodiertes PDF}</base64file>
</pdf>
Signiertes PDF zu einer Gutschrift hochladen
PUT /api/credit-notes/{id}/upload-signature
Lädt ein PDF mit einer digitalen Signatur zur angegebenen Gutschrift hoch.
Die Gutschrift darf sich nicht mehr im Entwurfs-Status (DRAFT) befinden.
XML-Element |
Beschreibung |
Typ |
Default-Wert |
Pflichtfeld |
base64file |
Base64-kodiertes PDF mit digitaler Signatur |
BASE64FILE |
|
ja |
Hinweis: Eine (qualifizierte) digitale Signatur kann NICHT direkt über die billomat[API] erstellt werden. Wir empfehlen, für diese Funktion direkt auf die PixelLetter-Schnittstelle oder einen anderen Dienst zurück zu greifen.
<signature>
<base64file>{base64-kodiertes PDF}</base64file>
</signature>
Gutschrift per E-Mail versenden
POST /api/credit-notes/{id}/email
XML-Element |
Beschreibung |
Typ |
Default-Wert |
Pflichtfeld |
email_template_id |
ID der E-Mail-Vorlage |
INT |
|
|
from |
Absender |
EMAIL |
Standard-E-Mail aus Einstellungen |
|
recipients |
Empfänger der E-Mail. Muss mindestens einen XML-Knoten „to“, „cc“ und/oder „bcc“ mit den gewünschten E-Mail-Adressen enthalten |
XML-Knoten/EMAIL |
|
ja |
subject |
Betreff der E-Mail, kann Platzhalter enthalten |
ALNUM |
Wert aus der (Standard-)E-Mail-Vorlage |
|
body |
Text der Mail, kann Platzhalter enthalten |
ALNUM |
Wert aus der (Standard-)E-Mail-Vorlage |
|
filename |
Dateiname der PDF-Gutschrift (ohne .pdf) |
ALNUM |
credit-note_{id} |
|
attachments |
Weitere Dateianhänge. Kann beliebig viele Dateianhänge über die Knoten „attachment“ mit den Elementen „filename“, „mimetype“ und „base64file“ enthalten |
XML-Knoten |
|
|
<email>
<from>info@billomat.com</from>
<recipients>
<to>info@billomat.com</to>
<cc>mail@example.com</cc>
</recipients>
<subject>Ihre Gutschrift</subject>
<body>Sehr geehrte Damen und Herren, ....</body>
<filename>gutschrift</filename>
<attachments>
<attachment>
<filename>zeichnung.pdf</filename>
<mimetype>application/pdf</mimetype>
<base64file>{base64-kodierte Datei}</base64file>
</attachment>
</attachments>
</email>
Gutschrift per Brief versenden
POST /api/credit-notes/{id}/mail
Versendet eine Gutschrift per Brief. Dazu muss Pixelletter als Add-On eingerichtet sein.
XML-Element |
Beschreibung |
Typ |
Default-Wert |
Pflichtfeld |
color |
Zeigt an, ob ein Farbdruck beauftragt werden soll. |
BOOL |
0 |
|
duplex |
Zeigt an, ob Duplexdruck beauftragt werden soll. |
BOOL |
1 |
|
paper_weight |
Welche Papierstärke in Gramm soll das Papier haben? Mögliche Werte sind 80 oder 90. |
INT |
90 |
|
attachments |
PDF Dateien, die zusätzlich mit gedruckt werden sollen. Kann beliebig viele Dateien über die Knoten „attachment“ mit den Elementen „filename“, „mimetype“ und „base64file“ enthalten. |
XML-Knoten |
|
|
<mail>
<color>0</color>
<duplex>1</duplex>
<paper_weight>90</paper_weight>
<attachments>
<attachment>
<filename>zeichnung.pdf</filename>
<mimetype>application/pdf</mimetype>
<base64file>{base64-kodierte Datei}</base64file>
</attachment>
</attachments>
</mail>
Gutschrift stornieren
PUT /api/credit-notes/{id}/cancel
Stornieren rückgängig machen
PUT /api/credit-notes/{id}/uncancel