Invoices

List all invoices

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>

You can fil­ter the result by parameters:

GET /api/invoices?invoice_number=RE123

Lists all invoices with “RE123” in the invoice num­ber. Upper and lower case are igno­red.
The fol­lo­wing fil­ter para­me­ters are available:

Aggre­ga­ted list of invoices

GET /api/invoices?group_by=client

Invoices can also be found grou­ped toge­ther. The above example all invoices grou­ped by cli­ent.
The fol­lo­wing values ​​are for para­me­ter group_by are available:

It can also be grou­ped accor­ding to several cri­te­ria. The desi­red values ​​are sim­ply con­ca­te­na­ted by com­mas (?group_by=client,year). The order of values ​​deter­mi­nes the order of aggregation.

The grou­ping para­me­ters can also be com­bi­ned with the other filters.

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

Get a sin­gle invoice

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>
    <label>project 123</label>
    <intro>We are pleased to offer you the following items into account:</intro>
    <note>Thank you for your order!</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>
    <payment_types>CASH,BANK_TRANSFER,PAYPAL</payment_types>
</invoice>

sta­tus can have the fol­lo­wing values:

• DRAFT
• OPEN
• OVERDUE
• PAID
• CANCELED

supply_date_type can have the fol­lo­wing values:

• SUPPLY_DATE (supply date as date)
• DELIVERY_DATE (deli­very date as date)
• SUPPLY_TEXT (supply date as free text)
• DELIVERY_TEXT (deli­very date as free text)

In addi­tion to the invoice com­bi­ned taxes (taxes) will be returned.

The accep­ted pay­ment types are sepa­ra­ted by comma. You can find a list of all pay­ment types at pay­ments docu­men­ta­tion.

Invoice items, com­ments and pay­ments can be acces­sed separately.

Create an invoice

POST /api/invoices

sta­tus at crea­tion is always DRAFT.
The remai­ning pro­per­ties of the account are auto­ma­ti­cally cal­cu­la­ted.
Invoice items (invoice-items) can be spe­ci­fied directly at crea­tion. Please find a docu­men­ta­tion of the XML ele­ments at Create invoice items, butthe XML ele­ment invoice_id need not be spe­ci­fied with.

<invoice>
    <client_id>1</client_id>
    <date>2009-11-18</date>
    <note>Thank you for your order</note>
    <invoice-items>
        <invoice-item>
            <unit>Piece</unit>
            <unit_price>1.23</unit_price>
            <quantity>1.5</quantity>
            <title>Model</title>
        </invoice-item>
        <invoice-item>
            <unit>hour</unit>
            <unit_price>90</unit_price>
            <quantity>8</quantity>
            <title>Work</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>

Edit invoice

PUT /api/invoices/{id}

Updates an invoice with the given para­me­ters.
An invoice can basi­cally be edi­ted in draft sta­tus (DRAFT) only.
Invoice items and com­ments could not be edi­ted at the invoice. Please use the appro­priate resource instead.

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

Delete invoice

DELETE /api/invoices/{id}

Dele­tes an invoice with all docu­ments (PDFs), items and com­ments.

Open pdf of an invoice

GET /api/invoices/{id}/pdf

At this point, the para­me­ter format=pdf can also be used to open the PDF directly with MIME type “application/pdf”.

<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 encoded PDF}</base64file>
</pdf>

Com­plete invoice

PUT /api/invoices/{id}/complete

Clo­ses a state­ment in the draft sta­tus (DRAFT) from. Here, the sta­tus of open (OPEN) or over­due (Over­due) is set and a PDF is gene­ra­ted and stored in the file sys­tem.
The optio­nal par­am­ter template_id deter­mi­nes which Tem­plate is used to create a pdf.
If this para­me­ter is not spe­ci­fied, the default tem­plate set is used.

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

Updoad a digi­tal signa­ture for a given invoice

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

Updoads a digi­tal signa­ture for a given invoice.
The sta­tus of the invo­cie may not be DRAFT.

Note: A (qua­lit­fied) digi­tal signa­ture can NOT be crea­ted by the billomat[API] directly. We recom­mend that you use this func­tion directly on the Pixel­Let­ter inter­face or ano­ther service.

<signature>
    <base64file>{base64 encoded PDF}</base64file>
</signature>

Send invoice by e-mail

POST /api/invoices/{id}/email

Sends an invoice by e-mail.

<email>
    <from>info@billomat.com</from>
    <recipients>
        <to>info@billomat.com</to>
        <cc>mail@example.com</cc>
    </recipients>
    <subject>Your invoice</subject>
    <body>Dear sir or madam, ....</body>
    <filename>invoice</filename>
    <attachments>
        <attachment>
            <filename>drawing.pdf</filename>
            <mimetype>application/pdf</mimetype>
            <base64file>{base64 encoded file}</base64file>
        </attachment>
    </attachments>
</email>

Can­cel invoice

PUT /api/invoices/{id}/cancel