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:

ParameterDescription
client_idID of the client
contact_idID of the contact
offer_numberEstimate number
statusStatus 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.
fromOnly show estimates since this date (format YYYY-MM-DD)
toOnly show estimates to this date (format YYYY-MM-DD)
labelFree text search in label text
introFree text search in introductory text
noteFree text search in explanatory notes
tagsComma separated list of tags
article_idID 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 elementDescriptionTypeDefault valueMandatory
client_idID of the clientINTyes
contact_idID of the contactINT
addressthe addressALNUMClient’s address
number_prePrefixALNUMValue taken from the settings
numberserial numberINTnext free number
number_lengthMinimum length of the estimate number (to be filled with leading zeros)INTValue taken from the settings
dateEstimate dateDATEtoday
titleTitle of the documentALNUM
labelLabel text to describe the projectALNUM
introIntroductory textALNUMValue taken from the settings
noteExplanatory notesALNUMValue taken from the settings
reductionReduction (absolute or percent: 10/10%)ALNUM
currency_codeCurrencyISO currency codeDefault currency from the settings
net_grossPrice basis (gross or net prices)ALNUM (“NET”, “GROSS”)Default value taken from the settings
quoteCurrency quote (for conversion into standard currency)FLOAT1.0000
validity_dateDate of validtiyDATE
free_text_idThe ID of the free text to set title, label, intro and note.INT
template_idThe ID of the template to be used to complete the estimate.INTID 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 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/EMAILyes
subjectSubject of the e-mail (may include placeholdersALNUMValue 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)ALNUMoffer_{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 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 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>

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