Working with Invoices in Billomat

Overview

The following operations allow you to work with invoices. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with invoices, see Sample configuration.

Operation	Description
createInvoice	Creates an invoice.
getInvoice	Retrieves an invoice's details by its ID.
listInvoices	Retrieves all invoices.
updateInvoice	Updates the details of the invoice.
completeInvoice	Completes the created invoice.
sendInvoice	Sends the completed invoice.

Operation details

This section provides further details on the operations related to invoices.

Creating an invoice

The createInvoice operation creates an invoice.

createInvoice

<billomat.createInvoice>
    <clientId>{$ctx:clientId}</clientId>
    <contactId>{$ctx:contactId}</contactId>
    <address>{$ctx:address}</address>
    <numberPre>{$ctx:numberPre}</numberPre>
    <number>{$ctx:number}</number>
    <numberLength>{$ctx:numberLength}</numberLength>
    <date>{$ctx:date}</date>
    <supplyDate>{$ctx:supplyDate}</supplyDate>
    <supplyDateType>{$ctx:supplyDateType}</supplyDateType>
    <dueDate>{$ctx:dueDate}</dueDate>
    <discountRate>{$ctx:discountRate}</discountRate>
    <discountDate>{$ctx:discountDate}</discountDate>
    <title>{$ctx:title}</title>
    <label>{$ctx:label}</label>
    <introduction>{$ctx:introduction}</introduction>
    <note>{$ctx:note}</note>
    <reduction>{$ctx:reduction}</reduction>
    <currencyCode>{$ctx:currencyCode}</currencyCode>
    <netGross>{$ctx:netGross}</netGross>
    <quote>{$ctx:quote}</quote>
    <paymentTypes>{$ctx:paymentTypes}</paymentTypes>
    <existingInvoiceId>{$ctx:existingInvoiceId}</existingInvoiceId>
    <offerId>{$ctx:offerId}</offerId>
    <confirmationId>{$ctx:confirmationId}</confirmationId>
    <recurringId>{$ctx:recurringId}</recurringId>
	<invoiceItems>{$ctx:invoiceItems}</invoiceItems>
</billomat.createInvoice>

Properties

clientId: The ID of the client.
contactId: The ID of the contact.
address: Address for the invoice.
numberPre: Invoice number prefix.
number: Serial number for the invoice.
numberLength: Minimum length of the invoice number (to be filled with leading zeros).
date: Invoice date of the invoice.
supplyDate: Supply/delivery date of the products of the invoice.
supplyDateType: Type of supply/delivery date.
dueDate: Due date of the invoice.
discountRate: Cash discount of the invoice.
discountDate: Cash discount date of the invoice.
title: Title of the document.
label: Label text to describe the project.
introduction: Introductory text of the invoice.
note: Explanatory notes of the invoice.
reduction: Reduction (absolute or percent: 10/10%).
currencyCode: Currency of the invoice.
netGross: Price basis (gross or net prices) of the invoice.
quote: Currency quote (for conversion into standard currency).
paymentTypes: List (separated by comma) of all accepted payment types.
existingInvoiceId: The ID of the corrected invoice, if it is an invoice correction.
offerId: The ID of the estimate, if the invoice was created from an estimate.
confirmationId: The ID of the confirmation, if the invoice was created from a confirmation.
recurringId: The ID of the recurring, if the invoice was created from a recurring.
invoiceItems: Array of invoice items to be added to the invoice.

Sample request

Following is a sample REST/JSON request that can be handled by the createInvoice operation.

Sample Request for createInvoice

{
    "clientId": "34354",
    "contactId": "45454",
    "address": "45,Mulheim, Germany",
    "numberPre": "in",
    "number": "12",
    "numberLength": "1",
    "date": "2015-06-18",
    "supplyDate": "2015-06-18",
    "supplyDateType": "SUPPLY_DATE",
    "dueDate": "2015-06-18",
    "discountRate": "23",
    "discountDate": "2015-06-19",
    "title": "billomatInvoice",
    "label": "l1",
    "introduction": "invoice is started",
    "note": "due on monday",
    "reduction": "23",
    "currencyCode": "UK",
    "netGross": "0",
    "quote": "45",
    "paymentTypes": "CASH",
    "existingInvoiceId": "23434",
    "offerId": "3434",
    "confirmationId": "34",
    "recurringId": "12",
    "invoiceItems": [
		"invoice-item": {
			"name":"choco"
		}
	],
    "apiUrl": "https://mycompany.billomat.net",
    "apiKey": "735478efc440e219669e243c0fd71840",
    "format":"xml"
}

Retrieving an invoice's details by its ID

The getInvoice operation retrieves an invoice's details by its ID.

getInvoice

<billomat.getInvoice>
	<invoiceId>{$ctx:invoiceId}</invoiceId>
</billomat.getInvoice>

Properties

invoiceId: The ID of the invoice whose details would be retrieved.

Sample request

Following is a sample REST/JSON request that can be handled by the getInvoice operation.

Sample Request for getInvoice

{
    "invoiceId": "123343",
    "apiUrl": "https://mycompany.billomat.net",
    "apiKey": "735478efc440e219669e243c0fd71840",
    "format":"xml"
}

Retrieving all invoices

The listInvoices operation retrieves all invoices.

listInvoices

<billomat.listInvoices>
    <clientId>{$ctx:clientId}</clientId>
    <contactId>{$ctx:contactId}</contactId>
    <invoiceNumber>{$ctx:invoiceNumber}</invoiceNumber>
    <status>{$ctx:status}</status>
    <paymentType>{$ctx:paymentType}</paymentType>
    <from>{$ctx:from}</from>
    <to>{$ctx:to}</to>
    <label>{$ctx:label}</label>
    <introduction>{$ctx:introduction}</introduction>
    <note>{$ctx:note}</note>
    <tags>{$ctx:tags}</tags>
    <articleId>{$ctx:articleId}</articleId>
    <groupBy>{$ctx:groupBy}</groupBy>
    <page>{$ctx:page}</page>
    <perPage>{$ctx:perPage}</perPage>
	<orderBy>{$ctx:orderBy}</orderBy>
</billomat.listInvoices>

Properties

clientId: Filter results by ID of the client.
contactId: Filter results by ID of the contact.
invoiceNumber: Filter results by invoice number.
status: Filter results by Status (DRAFT, OPEN, PAID, OVERDUE, CANCELED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected.
paymentType: Filter results by Payment Type (e.g. CASH, BANK_TRANSFER, PAYPAL,). More than one payment type could be given as a comma separated list. Theses payment types will be logically OR-connected.
from: Only show invoices since this date (format YYYY-MM-DD).
to: Only show invoices up to this date (format YYYY-MM-DD).
label: Free text search in label text.
introduction: Free text search in introductory text.
note: Free text search in explanatory notes.
tags: Comma separated list of tags.
articleId: Filter results by ID of an article.
groupBy: Invoices can also be found grouped together based on the provided value.
page: Number of the page to return. Applies for paginated response.
perPage: Number of entries to return per page when results are paginated.
orderBy: Sorting orders to retrieve invoices.

Sample request

Following is a sample REST/JSON request that can be handled by the listInvoices operation.

Sample Request for listInvoices

{
    "clientId": "5466878",
    "contactId": "6767667",
    "invoiceNumber": "67676",
    "status": "DRAFT",
    "paymentType": "CASH",
    "from": "2014-08-12",
    "to": "2014-08-18",
    "label": "shop",
    "introduction": "invoice in progress",
    "note": "due on monday",
    "tags": "shops",
    "articleId": "233453",
    "groupBy": "client",
    "page": "1",
    "perPage": "1",
    "apiUrl": "https://mycompany.billomat.net",
    "apiKey": "735478efc440e219669e243c0fd71840",
    "format":"xml",
    "orderBy":"id+DESC"
}

Updating the details of the invoice

The updateInvoice operation updates the details of the invoice.

updateInvoice

<billomat.updateInvoice>
    <clientId>{$ctx:clientId}</clientId>
    <contactId>{$ctx:contactId}</contactId>
    <address>{$ctx:address}</address>
    <numberPre>{$ctx:numberPre}</numberPre>
    <number>{$ctx:number}</number>
    <numberLength>{$ctx:numberLength}</numberLength>
    <date>{$ctx:date}</date>
    <supplyDate>{$ctx:supplyDate}</supplyDate>
    <supplyDateType>{$ctx:supplyDateType}</supplyDateType>
    <dueDate>{$ctx:dueDate}</dueDate>
    <discountRate>{$ctx:discountRate}</discountRate>
    <discountDate>{$ctx:discountDate}</discountDate>
    <title>{$ctx:title}</title>
    <label>{$ctx:label}</label>
    <introduction>{$ctx:introduction}</introduction>
    <note>{$ctx:note}</note>
    <reduction>{$ctx:reduction}</reduction>
    <currencyCode>{$ctx:currencyCode}</currencyCode>
    <netGross>{$ctx:netGross}</netGross>
    <quote>{$ctx:quote}</quote>
    <paymentTypes>{$ctx:paymentTypes}</paymentTypes>
    <existingInvoiceId>{$ctx:existingInvoiceId}</existingInvoiceId>
    <offerId>{$ctx:offerId}</offerId>
    <confirmationId>{$ctx:confirmationId}</confirmationId>
    <recurringId>{$ctx:recurringId}</recurringId>
	<invoiceId>{$ctx:invoiceId}</invoiceId>
</billomat.updateInvoice>

Properties

clientId: The ID of the client.
contactId: The ID of the contact.
address: Address for the invoice.
numberPre: Invoice number prefix.
number: Serial number for the invoice.
numberLength: Minimum length of the invoice number (to be filled with leading zeros).
date: Invoice date of the invoice.
supplyDate: Supply/delivery date of the products of the invoice.
supplyDateType: Type of supply/delivery date.
dueDate: Due date of the invoice.
discountRate: Cash discount of the invoice.
discountDate: Cash discount date of the invoice.
title: Title of the document.
label: Label text to describe the project.
introduction: Introductory text of the invoice.
note: Explanatory notes of the invoice.
reduction: Reduction (absolute or percent: 10/10%).
currencyCode: Currency of the invoice.
netGross: Price basis (gross or net prices) of the invoice.
quote: Currency quote (for conversion into standard currency).
paymentTypes: List (separated by comma) of all accepted payment types.
existingInvoiceId: The ID of the corrected invoice, if it is an invoice correction.
offerId: The ID of the estimate, if the invoice was created from an estimate.
confirmationId: The ID of the confirmation, if the invoice was created from a confirmation.
recurringId: The ID of the recurring, if the invoice was created from a recurring.
invoiceId: The ID of the invoice to update.

Sample request

Following is a sample REST/JSON request that can be handled by the updateInvoice operation.

Sample Request for updateInvoice

{
    "clientId": "34354",
    "contactId": "45454",
    "address": "45,Mulheim, Germany",
    "numberPre": "in",
    "number": "12",
    "numberLength": "1",
    "date": "2015-06-18",
    "supplyDate": "2015-06-18",
    "supplyDateType": "SUPPLY_DATE",
    "dueDate": "2015-06-18",
    "discountRate": "23",
    "discountDate": "2015-06-19",
    "title": "billomatInvoice",
    "label": "l1",
    "introduction": "invoice is started",
    "note": "due on monday",
    "reduction": "23",
    "currencyCode": "UK",
    "netGross": "0",
    "quote": "45",
    "paymentTypes": "CASH",
    "existingInvoiceId": "23434",
    "offerId": "3434",
    "confirmationId": "34",
    "recurringId": "12",
    "invoiceId": "23232",
    "apiUrl": "https://mycompany.billomat.net",
    "apiKey": "735478efc440e219669e243c0fd71840",
    "format":"xml"
}

Completing the created invoice

The completeInvoice operation completes the created invoice.

completeInvoice

<billomat.completeInvoice>
    <templateId>{$ctx:templateId}</templateId>
	<invoiceId>{$ctx:invoiceId}</invoiceId>
</billomat.completeInvoice>

Properties

templateId: The ID of the template from which the PDF is generated.
invoiceId: The ID of the invoice which is going to get completed.

Sample request

Following is a sample REST/JSON request that can be handled by the completeInvoice operation.

Sample Request for completeInvoice

{
   "apiUrl": "https://mycompany.billomat.net",
   "apiKey": "735478efc440e219669e243c0fd71840",
	"invoiceId":"1586475",
	"templateId":"invalid"
}

Sending the completed invoice

The sendInvoice operation sends the completed invoice.

sendInvoice

<billomat.sendInvoice>
    <emailBody>{$ctx:emailBody}</emailBody>
    <recipients>{$ctx:recipients}</recipients>
    <invoiceId>{$ctx:invoiceId}</invoiceId>
    <subject>{$ctx:subject}</subject>
    <fileName>{$ctx:fileName}</fileName>
    <fromEmail>{$ctx:fromEmail}</fromEmail>
	<attachments>{$ctx:attachments}</attachments>
</billomat.sendInvoice>

Properties

emailBody: Text body of the e-mail.
recipients: Recipients of the e-mail. There must be at least one XML note for 'to', 'cc' and/or 'bcc'.
invoiceId: The ID of the invoice to be sent.
subject: Subject of the e-mail.
fileName: Name of the PDF file (without .pdf).
fromEmail: Sender's email address.
attachments: Further files. Attachments can contain as many nodes on the 'attachment' with the elements 'filename', 'mimetype' and 'base64file'.

Sample request

Following is a sample REST/JSON request that can be handled by the sendInvoice operation.

Sample Request for sendInvoice

{
   "apiUrl": "https://mycompany.billomat.net",
    "apiKey": "735478efc440e219669e243c0fd71840",
	"invoiceId":"1566418",
	"recipients":{
        "to":"yasasitest@gmail.com"
    },
    "subject":"Reciept for the transaction",
    "emailBody":"This is a reciepet for the medicines.Thank you",
    "fileName":"reciept1"
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to Billomat with the init operation and use the createInvoice operation. The sample request for this proxy can be found in the createInvoice sample request.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="billomat_createInvoice" startOnLoad="true" statistics="disable" trace="disable" transports="https,http" xmlns="http://ws.apache.org/ns/synapse">
   <target>
      <inSequence onError="faultHandlerSeq">
         <property name="apiUrl" expression="json-eval($.apiUrl)"/>
         <property name="apiKey" expression="json-eval($.apiKey)"/>
         <property name="clientId" expression="json-eval($.clientId)"/>
         <property name="contactId" expression="json-eval($.contactId)"/>
         <property name="address" expression="json-eval($.address)"/>
         <property name="numberPre" expression="json-eval($.numberPre)"/>
         <property name="number" expression="json-eval($.number)"/>
         <property name="numberLength" expression="json-eval($.numberLength)"/>
         <property name="date" expression="json-eval($.date)"/>
         <property name="supplyDate" expression="json-eval($.supplyDate)"/>
         <property name="supplyDateType" expression="json-eval($.supplyDateType)"/>
         <property name="dueDate" expression="json-eval($.dueDate)"/>
         <property name="discountRate" expression="json-eval($.discountRate)"/>
         <property name="discountDate" expression="json-eval($.discountDate)"/>
         <property name="title" expression="json-eval($.title)"/>
         <property name="label" expression="json-eval($.label)"/>
         <property name="introduction" expression="json-eval($.introduction)"/>
         <property name="note" expression="json-eval($.note)"/>
         <property name="reduction" expression="json-eval($.reduction)"/>
         <property name="currencyCode" expression="json-eval($.currencyCode)"/>
         <property name="netGross" expression="json-eval($.netGross)"/>
         <property name="quote" expression="json-eval($.quote)"/>
         <property name="paymentTypes" expression="json-eval($.paymentTypes)"/>
         <property name="existingInvoiceId" expression="json-eval($.existingInvoiceId)"/>
         <property name="offerId" expression="json-eval($.offerId)"/>
         <property name="confirmationId" expression="json-eval($.confirmationId)"/>
         <property name="recurringId" expression="json-eval($.recurringId)"/>
         <property name="invoiceItems" expression="json-eval($.invoiceItems)"/>
         <property name="format" expression="json-eval($.format)"/>
         <billomat.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <apiKey>{$ctx:apiKey}</apiKey>
			<format>{$ctx:format}</format>
         </billomat.init>
         <billomat.createInvoice>
            <clientId>{$ctx:clientId}</clientId>
            <contactId>{$ctx:contactId}</contactId>
            <address>{$ctx:address}</address>
            <numberPre>{$ctx:numberPre}</numberPre>
            <number>{$ctx:number}</number>
            <numberLength>{$ctx:numberLength}</numberLength>
            <date>{$ctx:date}</date>
            <supplyDate>{$ctx:supplyDate}</supplyDate>
            <supplyDateType>{$ctx:supplyDateType}</supplyDateType>
            <dueDate>{$ctx:dueDate}</dueDate>
            <discountRate>{$ctx:discountRate}</discountRate>
            <discountDate>{$ctx:discountDate}</discountDate>
            <title>{$ctx:title}</title>
            <label>{$ctx:label}</label>
            <introduction>{$ctx:introduction}</introduction>
            <note>{$ctx:note}</note>
            <reduction>{$ctx:reduction}</reduction>
            <currencyCode>{$ctx:currencyCode}</currencyCode>
            <netGross>{$ctx:netGross}</netGross>
            <quote>{$ctx:quote}</quote>
            <paymentTypes>{$ctx:paymentTypes}</paymentTypes>
            <existingInvoiceId>{$ctx:existingInvoiceId}</existingInvoiceId>
            <offerId>{$ctx:offerId}</offerId>
            <confirmationId>{$ctx:confirmationId}</confirmationId>
            <recurringId>{$ctx:recurringId}</recurringId>
            <invoiceItems>{$ctx:invoiceItems}</invoiceItems>
         </billomat.createInvoice>
         <respond/>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
   </target>
   <description/>
</proxy>

WSO2 ESB Connectors Documentation

Working with Invoices in Billomat

Overview

Operation details

Creating an invoice

Properties

Sample request

Related Billomat documentation

Retrieving an invoice's details by its ID

Properties

Sample request

Related Billomat documentation

Retrieving all invoices

Properties

Sample request

Related Billomat documentation

Updating the details of the invoice

Properties

Sample request

Related Billomat documentation

Completing the created invoice

Properties

Sample request

Related Billomat documentation

Sending the completed invoice

Properties

Sample request

Related Billomat documentation

Sample configuration