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>
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:
Parameter | Description |
---|---|
client_id | ID of the client |
contact_id | ID of the contact |
invoice_number | invoice number |
status | Status (DRAFT, OPEN, PAID, OVERDUE, CANCELED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected. |
payment_type | Payment Type (eg. CASH, BANK_TRANSFER, PAYPAL, …). More than one payment type could be given as a comma separated list. Theses payment types will be logically OR-connected. You can find a overview of all payment types at API documentation of payments. |
from | Only show invoices since this date (format YYYY-MM-DD) |
to | Only show invoices up to this date (format YYYY-MM-DD) |
label | Free text search in label text |
intro | Free text search in introductory text |
note | Free text search in explanatory notes |
tags | Comma separated list of tags |
article_id | ID of an article |
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:
Value | Description |
---|---|
client | client |
status | status of an invoice |
day | day |
week | week (starts with monday) |
month | month |
year | year |
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 /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;amp;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>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> <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 can have the following values:
supply_date_type can have the following values:
net_gross can have the following values:
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.
POST /api/invoices
XML element | Description | Type | Default value | Mandatory |
---|---|---|---|---|
client_id | ID of the client | INT | yes | |
contact_id | ID of the contact | INT | ||
address | the address | ALNUM | client’s address | |
number_pre | invoice number prefix | ALNUM | Value taken from the settings | |
number | serial number | INT | next free number | |
number_length | Minimum length of the invoice number (to be filled with leading zeros) | INT | Value taken from the settings | |
date | Invoice date | DATE | today | |
supply_date | supply/delivery date | MIXED (DATE/ALNUM) | ||
supply_date_type | type of supply/delivery date | ALNUM (“SUPPLY_DATE”, “DELIVERY_DATE”, “SUPPLY_TEXT”, “DELIVERY_TEXT”) | ||
due_date | due date | DATE | date + due days taken from the settings | |
discount_rate | Cash discount | INT | Value from the settings | |
discount_date | Cash discount date | DATE | date + cash discount days taken from the settings | |
title | Title of the document | ALNUM | ||
label | Label text to describe the project | ALNUM | ||
intro | Introductory text | ALNUM | Default value taken from the settings | |
note | Explanatory notes | ALNUM | default value taken from the settings | |
reduction | Reduction (absolute or percent: 10/10%) | ALNUM | ||
currency_code | Currency | ISO currency code | Default currency | |
net_gross | Price basis (gross or net prices) | ALNUM (“NET”, “GROSS”) | Default value taken from the settings | |
quote | Currency quote (for conversion into standard currency) | FLOAT | 1.0000 | |
payment_types | List (separated by comma) of all accepted payment types. | FLOAT | Default value taken from the settings | |
invoice_id | The ID of the corrected invoice, if it is an invoice correction. | INT | ||
offer_id | The ID of the estimate, if the invoice was created from an estimate. | INT | ||
confirmation_id | The ID of the confirmation, if the invoice was created from a confirmation. | INT | ||
recurring_id | The ID of the recurring, if the invoice was created from a recurring. | INT | ||
free_text_id | The ID of the free text to set title, label, intro and note. | INT | ||
template_id | The ID of the template to be used to complete the invoice. | INT | ID of the default template |
status at creation is always DRAFT.
When initially created in DRAFT state, the invoice_number is returned as an empty response. It is only on completion of an invoice that the invoice number is calculated and gets a value.
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> <number_length type="integer">0</number_length> <date type="date">2009-11-18</date> … </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 /api/invoices/{id}
Deletes an invoice with all documents (PDFs), items and comments.
PUT /api/invoices/{id}/complete
Completes an invoice in the draft status (DRAFT). Here, the status of open (OPEN), overdue (OVERDUE), or paid (PAID) is set and a PDF is generated and stored in the file system.
The optional parameter template_id determines which template is used to create a pdf.
If this parameter is not specified, the template specified at the invoice or the default template is used.
<complete> <template_id>123</template_id> </complete>
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>
PUT /api/invoices/{id}/upload-signature
Uploads a digital signature for a given invoice. The status of the invoice may not be DRAFT.
XML element | Description | Type | Default value | Mandatory |
---|---|---|---|---|
base64file | Base64 encoded PDF with digital signature | BASE64FILE | yes |
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>
POST /api/invoices/{id}/email
Sends an invoice by e-mail.
XML element | Description | Type | Default value | Mandatory |
---|---|---|---|---|
email_template_id | ID of the e-mail template | INT | ||
from | Sender | Default email from the settings | ||
recipients | Recipients of the e-mail. There must be at least one xml node for “to”, “cc” and/or “bcc”. | XML node/EMAIL | yes | |
subject | Subject of the e-mail (may include placeholders) | ALNUM | Value taken from the (default) e-mail template | |
body | Text of the e-mail (may include placeholders) | ALNUM | Value taken from the (default) e-mail template | |
filename | Name of the PDF file (without .pdf) | ALNUM | invoice_{id} | |
attachments | Further files. Attachments can contain as many nodes on the “attachment” with the elements “filename”, “mimetype” and “base64file”. | XML node |
<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>
POST /api/invoices/{id}/mail
Sends an invoice by mail. Pixelletter has to be configured as add on for usage.
XML element | Description | Type | Default value | Mandatory |
---|---|---|---|---|
color | Determines whether to use color printing. | BOOL | 0 | |
duplex | Determines whether to use duplex printing. | BOOL | 1 | |
paper_weight | Determines the paper weight in grams. Possible values are 80 or 90. | INT | 90 | |
attachments | Further PDF files. Attachments can contain as many nodes on the “attachment” with the elements “filename”, “mimetype” and “base64file”. | XML node |
<mail> <color>0</color> <duplex>1</duplex> <paper_weight>90</paper_weight> <attachments> <attachment> <filename>drawing.pdf</filename> <mimetype>application/pdf</mimetype> <base64file>{base64 encoded file}</base64file> </attachment> </attachments> </mail>
PUT /api/invoices/{id}/cancel
PUT /api/invoices/{id}/uncancel
PUT /api/invoices/{invoiceId}&amp;gt;/encash