GET /api/confirmations
<?xml version="1.0" encoding="UTF-8"?> <confirmations type="array" page="1" per_page="100" total="2"> <confirmation> … </confirmation> <confirmation> … </confirmation> </confirmations>
GET /api/confirmations?confirmation_number=AB123
Lists all invoices with “AB123” in the confirmation 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 |
confirmation_number | Confirmation number |
status | Status (DRAFT, COMPLETED, CANCELED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected. |
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/confirmations/{id}
<?xml version="1.0" encoding="UTF-8"?> <confirmation> <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> <confirmation_number>AB123</confirmation_number> <number type="integer">123</number> <number_pre>AB</number_pre> <number_length type="integer">0</number_length> <status>COMPLETED</status> <date type="date">2010-10-01</date> <address>Billomat GmbH &amp;amp;amp;amp; Co. KG Hollertszug 26 57562 Herdorf Deutschland</address> <title></title> <label>project 123</label> <intro>Dear sir or madam,…</intro> <note>Best regards</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> <currency_code>EUR</currency_code> <quote type="float">1.0000</quote> <customerportal_url>https://mybillomatid.billomat.net/customerportal/confirmations/show/entityId/123?hash=123456789aabbcc</customerportal_url> <taxes type="array"> <tax> <name>MwSt</name> <rate type="float">19.0</rate> <amount type="float">19.0</amount> </tax> </taxes> <offer_id></offer_id> <template_id></template_id> </confirmation>
status can have the following values:
POST /api/confirmations
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 | Prefix | ALNUM | Value taken from the settings | |
number | serial number | INT | next free number | |
number_length | Minimum length of the confirmationnumber (to be filled with leading zeros) | INT | Value taken from the settings | |
date | Date of the confirmation | DATE | today | |
title | Title of the document | ALNUM | ||
label | Label text to describe the project | ALNUM | ||
intro | Introductory text | ALNUM | Value taken from the settings | |
note | Explanatory notes | ALNUM | 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 | |
offer_id | The ID of the estimate, if the confirmation was created from an estimate. | 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 confirmation. | INT | ID of the default template |
status at creation is always DRAFT.
When initially created in DRAFT state, the confirmation_number is returned as an empty response. It is only on completion of a confirmation that the confirmation number is calculated and gets a value.
The remaining properties are automatically calculated.
Confirmation items (confirmation-items) can be specified directly at creation. Please find a documentation of the XML elements at Create confirmation items, but the XML element confirmation_id need not be specified with.
<confirmation> <client_id>5</client_id> <date>2009-11-17</date> <confirmation-items> <confirmation-item> <unit>Piece</unit> <unit_price>1.23</unit_price> <quantity>1.5</quantity> <title>Pattern</title> </confirmation-item> <confirmation-item> <unit>Piece</unit> <unit_price>1.23</unit_price> <quantity>5</quantity> <title>Pattern 2</title> </confirmation-item> </confirmation-items> </confirmation>
<?xml version="1.0" encoding="UTF-8"?> <confirmation> <id type="integer">1234</id> <client_id type="integer">5</client_id> <created type="datetime">2007-12-13T12:12:00+01:00</created> <confirmation_number>AB124</confirmation_number> <number type="integer">124</number> <number_pre>AB</number_pre> <number_length type="integer">0</number_length> <date type="date">2009-11-17</date> … </confirmation>
PUT /api/confirmations/{id}
A confirmation can basically be edited in draft status (DRAFT) only.
Items and comments could not be edited at the confirmation. Please use the appropriate resource instead.
<confirmation> <date>2009-10-13</date> </confirmation>
DELETE /api/confirmations/{id}
Deletes a confirmation with all documents (PDFs), items and comments.
PUT /api/confirmations/{id}/complete
Completes a confirmation in the draft status (DRAFT). Here, the status of open (OPEN) 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 confirmation or the default template is used.
<complete> <template_id>123</template_id> </complete>
GET /api/confirmations/{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> <confirmation_id type="integer">240</confirmation_id> <filename>confirmation_123.pdf</filename> <mimetype>application/pdf</mimetype> <filesize>70137</filesize> <base64file>{base64 encoded PDF}</base64file> </pdf>
POST /api/confirmations/{id}/email
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 | ja | |
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>Bestätigung des Auftrags</subject> <body>Dear sir or madam, ….</body> <filename>Confirmation</filename> <attachments> <attachment> <filename>drawing.pdf</filename> <mimetype>application/pdf</mimetype> <base64file>{base64 encoded file}</base64file> </attachment> </attachments> </email>
POST /api/confirmations/{id}/mail
Sends a confirmation 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/confirmations/{id}/cancel
PUT /api/confirmations/{id}/uncancel
PUT /api/confirmations/{id}/clear
PUT /api/confirmations/{id}/unclear
First, use the Preset function to retrieve a payload for the corresponding order confirmation (confirmation_id).
GET /api/invoices/preset?confirmation_id={id}
Pass the received payload to the invoice creation API:
POST /api/invoices
<invoice> ... </invoice>