Alle Rechnungen auflisten

GET /api/invoices

Response: 200 OK
<?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
invoice_number	Rechnungsnummer
status	Rechnungsstatus (DRAFT, OPEN, PAID, OVERDUE, CANCELED)
from	Nur Rechnung ab diesem Datum (Format YYYY-MM-DD)
to	Nur Rechnung bis zu diesem Datum (Format YYYY-MM-DD)
intro	Freitextsuche im Einleitungstext
note	Freitextsuche im Anmerkungstext

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.

Response: 200 OK
<?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}

Response: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<invoice>
    <id type="integer">1</id>
    <client_id type="integer">123</client_id>
    <created type="datetime">2007-12-13T12:12:00+01:00</created>
    <invoice_number>RE123</client_number>
    <number type="integer">123</number>
    <number_pre>RE</number_pre>
    <status>OPEN</status>
    <date type="date">2009-10-14</date>
    <due_date type="date">2009-10-24</due_date>
    <due_days type="integer">10</due_days>
    <address>Billomat GmbH &amp; Co. KG&#13;
Hollertszug 26&#13;
57562 Herdorf&#13;
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>
    <intro>Wir freuen uns, Ihnen folgende Positionen in Rechnung stellen zu drüfen:</intro>
    <note>Vielen Dank für Ihren Auftrag!</note>
    <total_gross type="float">119.0</total_gross>
    <total_net type="float">100.0</total_net>
    <currency_code>EUR</currency_code>
    <quote type="float">1.0000</quote>
    <taxes type="array">
        <tax>
            <name>MwSt</name>
            <rate type="float">19.0</rate>
            <amount type="float">19.0</amount>
        </tax>
    </taxes>
</invoice>

status kann folgende Werte haben:

DRAFT (Entwurf)
OPEN (offen)
OVERDUE (überfällig)
PAID (bezahlt)
CANCELED (storniert)

Zusätzlich zu der eigentlichen Rechnung werden noch die zusammengefassten Steuern (taxes) mit zurückgegeben.

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
address	komplette Rechnungsadresse	ALNUM	Adresse des Kunden
number_pre	Präfix	ALNUM	Wert aus Einstellungen
number	lfd. Nummer	INT	nächste freie Nummer
date	Rechnungsdatum	DATE	heute
due_date	Fälligkeitsdatum	DATE	date + Fälligkeit in Tagen aus Einstellungen
discount_rate	Skonto in Prozent	INT	Wert aus Einstellungen
discount_date	Skontodatum	DATE	date + Skontozeitraum in Tagen aus Einstellungen
intro	Einleitungstext	ALNUM	Wert aus Einstellungen
note	Anmerkungstext	ALNUM	Wert aus Einstellungen
currency_code	Währung	ISO-Währungscode	Standard-Währung
quote	Währungskurs (für Umrechnung in Standard-Währung)	FLOAT	1.0000

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.

Request Body
<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>

Response: 201 Created
<?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>
    <date type="date">2009-11-18</date>
    ...
</invoice>

Rechnung bearbeiten

PUT /api/invoices/{id}

Aktualisiert eine Rechnung mit den übergebenen Parametern.

Eine Rechnung kann grundsätzlich nur im Entwurfs-Status (DRAFT) bearbeitet werden.

Rechnungspositionen und Kommentare können nicht direkt über die Rechnung bearbeitet werden. Bitte dafür über die entsprechende Ressource gehen.

Request Body
<invoice>
    <date>2009-10-13</date>
</invoice>

Response: 200 OK

Rechnung löschen

DELETE /api/invoices/{id}

Löscht eine Rechnung inkl. aller dazugehöriger Dokumente (PDFs), Rechnungspositionen und Kommentare.

Response: 200 OK

PDFs einer Rechnung aufrufen

GET /api/invoices/{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.

Response: 200 OK
<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>

Rechnung abschließen

PUT /api/invoices/{id}/complete

Schließt eine Rechnung im Entwurfsstatus (DRAFT) ab. Dabei wird der Status auf offen (OPEN) bzw. überfällig (OVERDUE) gesetzt und ein PDF erzeugt und im Dateisystem abgelegt.

Welche Vorlage für die PDF-Erzeugung benutzt wird, steuert der Parameter optionale template_id.
Wir dieser Parameter nicht angegeben, wird die eingestellte Standard-Vorlage benutzt.

Request Body
<complete>
    <template_id>123</template_id>
</complete>

Response: 200 OK

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.

Request Body
<signature>
    <base64file>{base64-kodiertes PDF}</base64file>
</signature>

Response: 200 OK

Rechnung per E-Mail versenden

POST /api/invoices/{id}/email

Versendet eine Rechnung per E-Mail.

XML-Element	Beschreibung	Typ	Default-Wert	Pflichtfeld
from	Absender	EMAIL	E-Mail des eingeloggten Benutzers
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 Einstellungen
body	Text der Mail, kann Platzhalter enthalten	ALNUM	Wert aus Einstellungen
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

Request Body
<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>

Response: 200 OK

Rechnung stornieren

PUT /api/invoices/{id}/cancel

Response: 200 OK

Du bist hier: Startseite » API » Rechnungen

billomat[API]: Rechnungen