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:

ParameterDescription
client_idID of the client
contact_idID of the contact
supplier_idID of the Suppliers
statusStatus (DRAFT, COMPLETED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected.
fromOnly show letters since this date (format YYYY-MM-DD)
toOnly show letters up to this date (format YYYY-MM-DD)
labelFree text search in label text
introFree text search in the text
tagsComma 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 elementDescriptionTypeDefault valueMandatory
client_idID of the clientINTyes
contact_idID of the contactINT
supplier_idID of the SuppliersINTyes
addressthe addressALNUMclient’s address
dateDate of the letterDATEtoday
subjectThe subjectALNUM
labelLabel text to describe the projectALNUM
introMessageALNUMDefault value taken from the settings
free_text_idThe ID of the free text to set subject (title), label and intro.INT
template_idThe ID of the template to be used to complete the letter.INTID 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 elementDescriptionTypeDefault valueMandatory
email_template_idID of the e-mail templateINT
fromSenderEMAILDefault email from the settings
recipientsRecipients of the e-mail. There must be at least one xml node for “to”, “cc” and/or “bcc”.XML node/EMAILja
subjectSubject of the e-mail (may include placeholders)ALNUMValue taken from the (default) e-mail template
bodyText of the e-mail (may include placeholders)ALNUMValue taken from the (default) e-mail template
filenameName of the PDF file (without .pdf)ALNUMinvoice_{id}
attachmentsFurther 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 elementDescriptionTypeDefault valueMandatory
colorDetermines whether to use color printing.BOOL0
duplexDetermines whether to use duplex printing.BOOL1
paper_weightDetermines the paper weight in grams. Possible values are 80 or 90.INT90
attachmentsFurther 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>