Letters

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></letter>
<address>Billomat GmbH & 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>

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>
    Dear sir or madam, ....
    <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>