Rechnungen

Alle Rech­nun­gen 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 Para­me­ter kann gefil­tert werden:

GET /api/invoices?invoice_number=RE123

Lis­tet alle Rech­nun­gen auf, die “RE123” in der Rech­nungs­num­mer haben. Groß– und Klein­schrei­bung wird igno­riert.
Fol­gende Filter-Parameter ste­hen zur Verfügung:

Rech­nun­gen aggre­giert auflisten

GET /api/invoices?group_by=client

Rech­nun­gen kön­nen auch grup­piert abge­ru­fen wer­den. Obi­ges Bei­spiel grup­piert alle Rech­nun­gen nach Kunde.
Fol­gende Werte ste­hen für den Para­me­ter group_byzur Ver­fü­gung:

Es kann auch nach meh­re­ren Kri­te­rien grup­piert wer­den. Dabei wer­den die gewünsch­ten Werte ein­fach per Komma anein­an­der­ge­hängt (?group_by=client,year). Die Rei­hen­folge der Werte bestimmt dabei die Rei­hen­folge der Aggregation.

Der Gruppierungs-Parameter kann auch mit den rest­li­chen Fil­tern kom­bi­niert 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>

Ein­zelne Rech­nung 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>
    <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>
    <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&#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>

sta­tus kann fol­gende Werte haben:

• DRAFT (Ent­wurf)
• OPEN (offen)
• OVERDUE (über­fäl­lig)
• PAID (bezahlt)
• CANCELED (stor­niert)

supply_date_type kann fol­gende Werte haben:

• SUPPLY_DATE (Leis­tungs­da­tum als Datum)
• DELIVERY_DATE (Lie­fer­da­tum als Datum)
• SUPPLY_TEXT (Leis­tungs­da­tum als Freitext)
• DELIVERY_TEXT (Lie­fer­da­tum als Freitext)

Zusätz­lich zu der eigent­li­chen Rech­nung wer­den noch die zusam­men­ge­fass­ten Steu­ern (taxes) mit zurückgegeben.

Die Rech­nungs­po­si­tio­nen, Rech­nungs­kom­men­tare und Zah­lun­gen kön­nen geson­dert abge­ru­fen werden.

Rech­nung erstellen

POST /api/invoices

Erstellt eine neue Rechnung.

sta­tus ist bei der Erstel­lung immer DRAFT.
Die übri­gen Eigen­schaf­ten der Rech­nung wer­den auto­ma­tisch berech­net.
Rech­nungs­po­si­tio­nen (invoice-items) kön­nen bei der Erstel­lung direkt mit ange­ge­ben wer­den. Es gel­ten die glei­chen XML-Elemente wie unter Rech­nungs­po­si­tion erstel­len. Nur das XML-Element invoice_id muss nicht mit ange­ge­ben 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>
    <date type="date">2009-11-18</date>
    ...
</invoice>

Rech­nung bearbeiten

PUT /api/invoices/{id}

Eine Rech­nung kann grund­sätz­lich nur im Entwurfs-Status (DRAFT) bear­bei­tet wer­den.
Rech­nungs­po­si­tio­nen und Kom­men­tare kön­nen nicht direkt über die Rech­nung bear­bei­tet wer­den. Bitte dafür über die ent­spre­chende Res­source gehen.

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

Rech­nung löschen

DELETE /api/invoices/{id}

Löscht eine Rech­nung inkl. aller dazu­ge­hö­ri­ger Doku­mente (PDFs), Rech­nungs­po­si­tio­nen und Kom­men­tare.

PDFs einer Rech­nung aufrufen

GET /api/invoices/{id}/pdf

Als optio­na­ler Para­me­ter kann type=signed ver­wen­det wer­den, um das digi­tal signierte PDF auf­zu­ru­fen.
An die­ser Stelle kann außer­dem der Para­me­ter format=pdf ver­wen­det wer­den, um das PDF direkt mit Mime­type “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>

Rech­nung abschließen

PUT /api/invoices/{id}/complete

Schließt eine Rech­nung im Ent­wurfs­sta­tus (DRAFT) ab. Dabei wird der Sta­tus auf offen (OPEN) bzw. über­fäl­lig (OVERDUE) gesetzt und ein PDF erzeugt und im Datei­sys­tem abge­legt.
Wel­che Vor­lage für die PDF-Erzeugung benutzt wird, steu­ert der Para­me­ter optio­nale template_id.
Wir die­ser Para­me­ter nicht ange­ge­ben, wird die ein­ge­stellte Standard-Vorlage benutzt.

<complete>
    <template_id>123</template_id>
</complete>

Signier­tes PDF zu einer Rech­nung hochladen

PUT /api/invoices/{id}/upload-signature

Lädt ein PDF mit einer digi­ta­len Signa­tur zur ange­ge­be­nen Rech­nung hoch.
Die Rech­nung darf sich nicht mehr im Entwurfs-Status (DRAFT) befinden.

Hin­weis: Eine (qua­li­fi­zierte) digi­tale Signa­tur kann NICHT direkt über die billomat[API] erstellt wer­den. Wir emp­feh­len, für diese Funk­tion direkt auf die PixelLetter-Schnittstelle oder einen ande­ren Dienst zurück zu greifen.

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

Rech­nung per E-Mail versenden

POST /api/invoices/{id}/email

ver­sen­det eine Rech­nung per E-Mail.

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

Rech­nung stornieren

PUT /api/invoices/{id}/cancel