[API] 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 filter the result by parameters:

GET /api/invoices?invoice_number=RE123

Lists all invoices with "RE123" in the invoice number. Upper and lower case are ignored.
The following filter parameters are available:

Aggregated list of invoices

GET /api/invoices?group_by=client

Invoices can also be found grouped together. The above example all invoices grouped by client.
The following values ​​are for parameter group/by_ are available:

It can also be grouped according to several criteria. The desired values ​​are simply concatenated by commas (?group_by=client,year). The order of values ​​determines the order of aggregation.

The grouping parameters can also be combined 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 single 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>
    <contact_id type="integer"></contact_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
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>
    <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">107.1</total_gross>
    <total_net type="float">90.0</total_net>
    <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>
    <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>
</invoice>

status can have the following values:

• DRAFT
• OPEN
• OVERDUE
• PAID
• CANCELED

supply_date_type can have the following values:

• SUPPLY_DATE (supply date as date)
• DELIVERY_DATE (delivery date as date)
• SUPPLY_TEXT (supply date as free text)
• DELIVERY_TEXT (delivery date as free text)

In addition to the invoice combined taxes (taxes) will be returned.

The accepted payment types are separated by comma. You can find a list of all payment types at payments documentation.

Invoice items, comments and payments can be accessed separately.

Create an invoice

POST /api/invoices

status at creation is always DRAFT.
The remaining properties of the account are automatically calculated.
Invoice items (invoice-items) can be specified directly at creation. Please find a documentation of the XML elements at Create invoice items, but the XML element invoice_id need not be specified 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 parameters.
An invoice can basically be edited in draft status (DRAFT) only.
Invoice items and comments could not be edited at the invoice. Please use the appropriate resource instead.

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

Delete invoice

DELETE /api/invoices/{id}

Deletes an invoice with all documents (PDFs), items and comments.

Complete invoice

PUT /api/invoices/{id}/complete

Closes a statement in the draft status (DRAFT) from. Here, the status of open (OPEN) or overdue (Overdue) is set and a PDF is generated and stored in the file system.
The optional paramter template_id determines which Template is used to create a pdf.
If this parameter is not specified, the default template set is used.

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

Open pdf of an invoice

GET /api/invoices/{id}/pdf

At this point, the parameter format=pdf can also be used to open the PDF directly with MIME type "application/pdf".

With the optional parameter type=print you can request the PDF without background. Note that the setting print_version must have been activated.

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

Upload a digital signature for a given invoice

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

Uploads a digital signature for a given invoice.
The status of the invocie may not be DRAFT.

Note: A (qualitfied) digital signature can NOT be created by the billomat[API] directly. We recommend that you use this function directly on the PixelLetter interface or another 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>

Cancel invoice

PUT /api/invoices/{id}/cancel