List all letters

GET /api/letters
<?xml version="1.0" encoding="UTF-8"?>
<letters type="array" page="1" per_page="100" total="2">
    <letter>
    ...
    </letter>
    <letter>
    ...
    </letter>
</letters>

You can filter the result by parameters:

GET /api/letters?subject=Order+123

Lists all letters with “Order 123” in the subject. 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
supplier_id ID of the Suppliers
status Status (DRAFT, COMPLETED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected.
from Only show letters since this date (format YYYY-MM-DD)
to Only show letters up to this date (format YYYY-MM-DD)
label Free text search in label text
intro Free text search in the text
tags Comma separated list of tags

Get a single letter

GET /api/letters/{id}
<?xml version="1.0" encoding="UTF-8"?>
<letter>
    <id type="integer">1</id>
    <created type="datetime">2014-12-13T12:12:00+01:00</created>
    <client_id type="integer">123</client_id>
    <contact_id type="integer"></contact_id>
    <supplier_id type="integer"></supplier_id>
    <status>COMPLETED</status>
    <date type="date">2014-10-14</date>
    <address>Billomat GmbH &amp; Co. KG
    Hollertszug 26
    57562 Herdorf
    Germany</address>
    <label>Project 123</label>
    <subject>Your order</subject>
    <intro>Dear sir or madam, ...</intro>
    <customerportal_url>https://mybillomatid.billomat.net/customerportal/letters/show/entityId/123?hash=123456789aabbcc</customerportal_url>
</letter>

status can have the following values:
– DRAFT
– COMPLETED

Create letter

POST /api/letters
XML element Description Type Default value Mandatory
client_id ID of the client INT yes
contact_id ID of the contact INT
supplier_id ID of the Suppliers INT yes
address the address ALNUM client’s address
date Date of the letter DATE today
subject The subject ALNUM
label Label text to describe the project ALNUM
intro Message ALNUM Default value taken from the settings
free_text_id The ID of the free text to set subject (title), label and intro. INT
template_id The ID of the template to be used to complete the letter. INT ID of the default template

status at creation is always DRAFT.

<letter>
    <client_id>1</client_id>
    <date>2009-11-18</date>
    <subject>Your order</subject>
    <intro>Dear sir or madam,...</intro>
</letter>
<?xml version="1.0" encoding="UTF-8"?>
<letter>
    <id type="integer">1234</id>
    <client_id type="integer">1</client_id>
    <created type="datetime">2014-12-13T12:12:00+01:00</created>
    <subject>Your order</subject>
    <intro>Dear sir or madam,...</intro>
    ...
</letter>

Edit letter

PUT /api/letters/{id}

A letter can basically be edited in draft status (DRAFT) only.

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

Delete letter

DELETE /api/letters/{id}

Deletes a letter with all documents (PDFs) and comments.

Complete letter

PUT /api/letters/{id}/complete

Completes a letter in the draft status (DRAFT). Here, the status completed (COMPLETED) 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 letter or the default template is used.

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

Open pdf of a letter

GET /api/letters/{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>
    <filename>letter_123.pdf</filename>
    <mimetype>application/pdf</mimetype>
    <filesize>70137</filesize>
    <base64file>{base64 encoded PDF}</base64file>
</pdf>

Send letter by e-mail

POST /api/letters/{id}/email
XML element Description Type Default value Mandatory
email_template_id ID of the e-mail template INT
from Sender EMAIL 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>Your letter</subject>
    <body>Dear sir or madam, ....</body>
    <filename>Letter</filename>
    <attachments>
        <attachment>
            <filename>attachment.pdf</filename>
            <mimetype>application/pdf</mimetype>
            <base64file>{base64 encoded file}</base64file>
        </attachment>
    </attachments>
</email>

Send letter by mail

POST /api/letters/{id}/mail

Sends a letter 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>