All docs This doc
Skip to end of metadata
Go to start of metadata


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

OperationDescription

createInvoice

Creates an invoice.

getInvoice

Retrieves an invoice's details by its ID.

listInvoicesRetrieves all invoices.
updateInvoiceUpdates the details of the invoice.
completeInvoiceCompletes the created invoice.
sendInvoiceSends 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"
}

Related Billomat documentation

http://www.billomat.com/en/api/invoices

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"
}
Related Billomat documentation

http://www.billomat.com/en/api/invoices

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"
}
Related Billomat documentation

http://www.billomat.com/en/api/invoices

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"
}
Related Billomat documentation

http://www.billomat.com/en/api/invoices

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"
}
Related Billomat documentation

http://www.billomat.com/en/api/invoices

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"
}
Related Billomat documentation

http://www.billomat.com/en/api/invoices

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>
  • No labels