Alle Rechnungen auflisten
GET /api/invoices
<?xml version="1.0" encoding="UTF-8"?> <invoices type="array" page="1" per_page="100" total="2"> <invoice> ... </invoice> <invoice> ... </invoice> </invoices>
Über Parameter kann gefiltert werden:
GET /api/invoices?invoice_number=RE123
Listet alle Rechnungen auf, die „RE123“ in der Rechnungsnummer 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 |
invoice_number | Rechnungsnummer |
status | Rechnungsstatus (DRAFT, OPEN, PAID, OVERDUE, CANCELED). Mehrere Stati können per Komma getrennt werden und werden ODER-Verknüpft. |
payment_type | Zahlart (z.B. CASH, BANK_TRANSFER, PAYPAL, …). Mehrere Zahlarten können per Komma getrennt werden und werden ODER-Verknüpft. Eine Übersicht aller Zahlarten findet man bei der API-Dokumentation für Zahlungen. |
from | Nur Rechnung ab diesem Datum (Format YYYY-MM-DD) |
to | Nur Rechnung 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 |
Rechnungen aggregiert auflisten
GET /api/invoices?group_by=client
Rechnungen können auch gruppiert abgerufen werden. Obiges Beispiel gruppiert alle Rechnungen nach Kunde.
Folgende Werte stehen für den Parameter group_by zur Verfügung:
Wert | Beschreibung |
---|---|
client | Kunde |
status | Rechnungsstatus |
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"?> <invoice-groups type="array" currency_code="USD"> <invoice-group> <total_gross type="float">347.28</total_gross> <total_net type="float">291.83</total_net> <client_id type="integer">476</client_id> <invoice-params> <client_id type="integer">476</client_id> </invoice-params> </invoice-group> <invoice-group> <total_gross type="float">1127.53</total_gross> <total_net type="float">947.50</total_net> <client_id type="integer">477</client_id> <invoice-params> <client_id type="integer">477</client_id> </invoice-params> </invoice-group> </invoice-groups>
Einzelne Rechnung aufrufen
GET /api/invoices/{id}
<?xml version="1.0" encoding="UTF-8"?> <invoice> <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> <invoice_number>RE123</invoice_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> <supply_date>2009-10-12</supply_date> <supply_date_type>SUPPLY_DATE</supply_date_type> <due_date type="date">2009-10-24</due_date> <due_days type="integer">10</due_days> <address>Billomat GmbH &amp; Co. KG Hollertszug 26& 57562 Herdorf Deutschland</address> <discount_rate type="float">2.0</discount_rate> <discount_date type="date">2009-10-21</discount_date> <discount_days type="integer">7</discount_days> <discount_amount type="float">2.0</discount_amount> <title></title> <label>Projekt 123</label> <intro>Wir freuen uns, Ihnen folgende Positionen in Rechnung stellen zu dürfen:</intro> <note>Vielen Dank für Ihren Auftrag!</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> <paid_amount type="float">20.0</paid_amount> <open_amount type="float">99.0</open_amount> <currency_code>EUR</currency_code> <quote type="float">1.0000</quote> <invoice_id></invoice_id> <offer_id></offer_id> <confirmation_id>7</confirmation_id> <recurring_id></recurring_id> <taxes type="array"> <tax> <name>MwSt</name> <rate type="float">19.0</rate> <amount type="float">19.0</amount> </tax> </taxes> <payment_types>CASH,BANK_TRANSFER,PAYPAL</payment_types> <customerportal_url>https://mybillomatid.billomat.net/customerportal/invoices/show/entityId/123?hash=123456789aabbcc</customerportal_url> <template_id></template_id> </invoice>
status kann folgende Werte haben:
– DRAFT (Entwurf)
– OPEN (offen)
– OVERDUE (überfällig)
– PAID (bezahlt)
– CANCELED (storniert)
supply_date_type kann folgende Werte haben:
– SUPPLY_DATE (Leistungsdatum als Datum)
– DELIVERY_DATE (Lieferdatum als Datum)
– SUPPLY_TEXT (Leistungsdatum als Freitext)
– DELIVERY_TEXT (Lieferdatum als Freitext)
net_gross kann folgende Werte haben:
– NET (Netto-Preise)
– GROSS (Brutto-Preise)
Zusätzlich zu der eigentlichen Rechnung werden noch die zusammengefassten Steuern (taxes) mit zurückgegeben.
Bei den Zahlarten handelt es sich um eine durch Komma getrennte Liste. Die Namen der Zahlarten werden bei den Zahlungen aufgelistet.
Die Rechnungspositionen, Rechnungskommentare und Zahlungen können gesondert abgerufen werden.
Rechnung erstellen
POST /api/invoices
Erstellt eine neue Rechnung.
XML-Element | Beschreibung | Typ | Default-Wert | Pflichtfeld |
---|---|---|---|---|
client_id | ID des Kunden | INT | ja | |
contact_id | ID des Kontakts | INT | ||
address | komplette Rechnungsadresse | 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 Rechnungsnummer (wird mit führenden Nullen aufgefüllt) | INT | Wert aus den Einstellungen | |
date | Rechnungsdatum | DATE | heute | |
supply_date | Liefer-/Leistungsdatum | MIXED (DATE/ALNUM) | ||
supply_date_type | Typ des Feldes Liefer-/Leistungsdatum | ALNUM („SUPPLY_DATE“, „DELIVERY_DATE“, „SUPPLY_TEXT“, „DELIVERY_TEXT“) | ||
due_days | Tage bis Fälligkeit | INT | Fälligkeit in Tagen aus Einstellungen | |
due_date | Fälligkeitsdatum | DATE | date + due_days | |
discount_rate | Skonto in Prozent | INT | Wert aus Einstellungen | |
discount_days | Skontozeitraum | INT | Skontozeitraum in Tagen aus Einstellungen | |
discount_date | Skontodatum | DATE | date + discount_days | |
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 | |
payment_types | akzeptierte Zahlarten (kommasepariert) | ALNUM | Wert aus den Einstellungen | |
invoice_id | Die ID der korrigierten Rechnung, wenn es sich um eine Korrekturrechnung handelt. | INT | ||
offer_id | Die ID des Angebots, wenn die Rechnung aus einem Angebot erstellt wurde. | INT | ||
confirmation_id | Die ID der Auftragsbestätigung, wenn die Rechnung aus einer Auftragsbestätigung erstellt wurde. | INT | ||
recurring_id | Die ID der Rechnung, wenn die Rechnung aus einer Abo-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 Rechnung abgeschlossen werden soll. | INT | ID der Standardvorlage |
status ist bei der Erstellung immer DRAFT.
Die übrigen Eigenschaften der Rechnung werden automatisch berechnet.
Rechnungspositionen (invoice-items) können bei der Erstellung direkt mit angegeben werden. Es gelten die gleichen XML-Elemente wie unter Rechnungsposition erstellen. Nur das XML-Element invoice_id muss nicht mit angegeben werden.
<invoice> <client_id>1</client_id> <date>2009-11-18</date> <note>Vielen Dank für Ihren Auftrag</note> <invoice-items> <invoice-item> <unit>Stück</unit> <unit_price>1.23</unit_price> <quantity>1.5</quantity> <title>Muster</title> </invoice-item> <invoice-item> <unit>Stunde</unit> <unit_price>90</unit_price> <quantity>8</quantity> <title>Arbeiten</title> </invoice-item> </invoice-items> </invoice>
<?xml version="1.0" encoding="UTF-8"?> <invoice> <id type="integer">1234</id> <client_id type="integer">1</client_id> <created type="datetime">2007-12-13T12:12:00+01:00</created> <invoice_number>RE124</invoice_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> ... </invoice>
Rechnung bearbeiten
PUT /api/invoices/{id}
Eine Rechnung kann grundsätzlich nur im Entwurfsstatus (DRAFT) bearbeitet werden.
Rechnungspositionen und Kommentare können nicht direkt über die Rechnung bearbeitet werden. Bitte dafür über die entsprechende Ressource gehen.
<invoice> <date>2009-10-13</date> </invoice>
Rechnung löschen
DELETE /api/invoices/{id}
Löscht eine Rechnung inkl. aller dazugehöriger Dokumente (PDFs), Rechnungspositionen und Kommentare.
Rechnung abschließen
PUT /api/invoices/{id}/complete
Schließt eine Rechnung im Entwurfsstatus (DRAFT) ab. Dabei wird der Status auf offen (OPEN), überfällig (OVERDUE) bzw. bezahlt (PAID) gesetzt und 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 Rechnung hinterlegte Vorlage oder die eingestellte Standardvorlage benutzt.
<complete> <template_id>123</template_id> </complete>
PDF einer Rechnung aufrufen
GET /api/invoices/{id}/pdf
Als optionaler Parameter kann type=signed verwendet werden, um das digital signierte 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.
An dieser Stelle kann außerdem der Parameter format=pdf verwendet werden, um das PDF direkt mit Mimetype „application/pdf“ aufzurufen.
<pdf> <id type="integer">4882</id> <created type="datetime">2009-09-02T12:04:15+02:00</created> <invoice_id type="integer">240</invoice_id> <filename>invoice_123.pdf</filename> <mimetype>application/pdf</mimetype> <filesize>70137</filesize> <base64file>{base64-kodiertes PDF}</base64file> </pdf>
Signiertes PDF zu einer Rechnung hochladen
PUT /api/invoices/{id}/upload-signature
Lädt ein PDF mit einer digitalen Signatur zur angegebenen Rechnung hoch.
Die Rechnung 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>
Rechnung per E-Mail versenden
POST /api/invoices/{id}/email
Versendet eine Rechnung per E-Mail.
XML-Element | Beschreibung | Typ | Default-Wert | Pflichtfeld |
---|---|---|---|---|
email_template_id | ID der E-Mail-Vorlage | INT | ||
from | Absender | 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-Rechnung (ohne .pdf) | ALNUM | invoice_{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 Rechnung</subject> <body>Sehr geehrte Damen und Herren, ....</body> <filename>rechnung</filename> <attachments> <attachment> <filename>zeichnung.pdf</filename> <mimetype>application/pdf</mimetype> <base64file>{base64-kodierte Datei}</base64file> </attachment> </attachments> </email>
Rechnung per Brief versenden
POST /api/invoices/{id}/mail
Versendet eine Rechnung 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>
Rechnung stornieren
PUT /api/invoices/{id}/cancel
Stornieren rückgängig machen
PUT /api/invoices/{id}/uncancel