Estimates

List all estimates

GET /api/offers
<!--?xml version="1.0" encoding="UTF-8"?-->
<offers type="array" page="1" per_page="100" total="2">
    <offer>
        ...
    </offer>
    <offer>
        ...
    </offer>
</offers>
The list can be filtered with parameters:
GET /api/offers?offer_number=AN123
Shows all clients with the term “AN123” in their offer number. It doesn’t matter if you use upper– or lowercase.
The following parameters can be used:
Parameter
Description
client_id
ID of the client
contact_id
ID of the contact
offer_number
Estimate number
status
Status of the estimate (DRAFT, OPEN, WON, LOST, CANCELED, CLEARED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected.
from
Only show estimates since this date (format YYYY-MM-DD)
to
Only show estimates 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 a single estimate
GET /api/offers/{id}
<!--?xml version="1.0" encoding="UTF-8"?-->
<offer>
    <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>
    <offer_number>AN123</offer_number>
    <number type="integer">123</number>
    <number_pre>AN</number_pre>
    <number_length type="integer">0</number_length>
    <status>OPEN</status>
    <date type="date">2010-10-01</date></offer>
<address>Billomat GmbH & Co. KG
Hollertszug 26
57562 Herdorf
Deutschland</address>

    <title></title>
    <label>project 123</label>
    <intro>We are pleased to offer you the following items:</intro>
    <note>We are looking forward to your answer.</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/offers/show/entityId/123?hash=123456789aabbcc</customerportal_url>
    <taxes type="array">
        <tax>
            <name>VAT</name>
            <rate type="float">19.0</rate>
            <amount type="float">19.0</amount>
        </tax>
    </taxes>
    <validity_date>2010-10-31</validity_date>
    <validity_days>30</validity_days>
    <template_id></template_id>

status can have the following values:
– DRAFT
– OPEN
– WON
– LOST
– CANCELED
– CLEARED
net_gross can have the following values:
– NET
– GROSS
In addition to the estimate combined taxes (taxes) will be returned.
Estimate items and comments can be accessed separately.
Create an estimate
POST /api/offers
Creates an estimate.
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 estimate number (to be filled with leading zeros)
INT
Value taken from the settings
date
Estimate date
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 from the settings
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
validity_date
Date of validtiy
DATE
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 estimate.
INT
ID of the default template
status at creation is always DRAFT.
The remaining properties are automatically calculated.
Estimate items (offer-items) can be specified directly at creation. Please find a documentation of the XML elements at Create estimate items, but the XML element offer_id need not be specified with.
<offer>
    <client_id>5</client_id>
    <date>2009-11-17</date>
    <offer-items>
        <offer-item>
            <unit>Piece</unit>
            <unit_price>1.23</unit_price>
            <quantity>1.5</quantity>
            <title>foo</title>
        </offer-item>
        <offer-item>
            <unit>Piece</unit>
            <unit_price>1.23</unit_price>
            <quantity>5</quantity>
            <title>bar</title>
        </offer-item>
    </offer-items>
</offer>
<!--?xml version="1.0" encoding="UTF-8"?-->
<offer>
    <id type="integer">1234</id>
    <client_id type="integer">5</client_id>
    <created type="datetime">2007-12-13T12:12:00+01:00</created>
    <offer_number>AN124</offer_number>
    <number type="integer">124</number>
    <number_pre>AN</number_pre>
    <number_length type="integer">0</number_length>
    <date type="date">2009-11-17</date>
    ...
</offer>
Edit estimate
PUT /api/offers/{id}
Updates an estimate with the given parameters.
An estimate can basically be edited in draft status (DRAFT) only.
Items and comments could not be edited at the estimate. Please use the appropriate resource instead.
<offer>
    <date>2009-10-13</date>
</offer>
Delete estimate
DELETE /api/offers/{id}
Deletes an estimate with all documents (PDFs), items and comments.
Complete estimate
PUT /api/offers/{id}/complete
Completes an estimate 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 estimate or the default template is used.
<complete>
    <template_id>123</template_id>
</complete>
Open pdf of an estimate
GET /api/offers/{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>
    <offer_id type="integer">240</offer_id>
    <filename>offer_123.pdf</filename>
    <mimetype>application/pdf</mimetype>
    <filesize>70137</filesize>
    <base64file>{base64 encoded PDF}</base64file>
</pdf>
Send an estimate by e-mail
POST /api/offers/{id}/email
Sends an estimate by e-mail.
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
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
offer_{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 estimate</subject>
    Dear sir or madam, ....
    <filename>estimate</filename>
    <attachments>
        <attachment>
            <filename>drawing.pdf</filename>
            <mimetype>application/pdf</mimetype>
            <base64file>{base64 encoded file}</base64file>
        </attachment>
    </attachments>
</email>
Send estimate by mail
POST /api/offers/{id}/mail
Sends an estimate 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>
Cancel estimate
PUT /api/offers/{id}/cancel
Undo cancellation
PUT /api/offers/{id}/uncancel
Mark estimate as won
PUT /api/offers/{id}/win
Mark estimate as lost
PUT /api/offers/{id}/lose
Mark estimate as cleared
PUT /api/offers/{id}/clear
Mark estimate as uncleared
PUT /api/offers/{id}/unclear