Acumulus API
Introduction
The Acumulus Application Interface (API) provides a connector that allows third party software vendors like webshop providers to directly communicate
with the application. Currently only adding a new invoice is supported since this is commonly most desired.
The import process of a new invoice into one or several Acumulus accounts, consists of two steps:
- saving all the necessary invoice data in a temporary XML file that can be accessed by Acumulus through a URL, for instance:
https://www.yourwebshop.com/somefolder/yourfile.xml
Use an ssl secured url (https) to ensure encryption.
- telling Acumulus where to find the XML file by calling the specific Acumulus api file with an additional file location parameter, for instance:
https://www.sielsystems.nl/acumulus/api/add_invoice.php?xmlfile=https://www.yourwebshop.com/somefolder/yourfile.xml
That's basically it!
All you have to do, is write a valid XML file and tell Acumulus where it is.
You will of course have to write some code that generates and saves the XML file. Please make sure you replace or remove all restricted characters like < > ' " and &. The import may fail if just one these characters appears in your data. You may use the php function htmlspecialchars() to convert your data. Do not use htmlentities() for this functions is strictly aimed at HTML and not XML.
htmlspecialchars() does not alter the & sign which will inevitably raise an error. Another way to have any data parsed correctly, is by wrapping each data element in a CDATA tag.
<![CDATA[12345]]>
where 12345 represents the actual data in the field.
Alternatively, the xml file can be posted as a string using curl, for instance:
<?php
$xml_string = urlencode($xml_string);
$url = "https://www.sielsystems.nl/acumulus/api/add_invoice.php";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "xmlstring=$xml_string");
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_exec($ch);
curl_close($ch);
?>
Do not use line breaks like \n when posting the XML data as a string but create one single long string!.
Generating the XML file
The XML file or string contains all relevant data of the Acumulus user, the customer and the invoice in a predefined field structure.
<?xml version="1.0" encoding="UTF-8"?>
Multiple contracts are allowed (if applicable), as well as multiple customers, invoices and lines. Note that the XML respons only returns the last invoicenumber. This implies that multiple inserts of invoices cannot return all respective invoice numbers in case these are generated by Acumulus (through leaving the number node empty). If the newly generated invoice number is needed for further processing, use single invoice inserts.
A minimalistic version
As certain values are non mandatory or set to their respective default values when ommited, one could succesfully use the following xml example:
<?xml version="1.0" encoding="UTF-8"?>
This will create a simple new invoice with an automatically generated invoice number and a date that equals the day of creation. The customer will be added and default values for costheading, accountnumber and template are applied. Since there is no information regarding the vat type, this will be considered a regular national invoice without reverse charge of vat or margin.
Just add a new contact
If the entire invoice section including it's primary nodes <invoice> and </invoice> is omitted, this import operates as a module to import contacts only.
<?xml version="1.0" encoding="UTF-8"?>
Node legend
contractcode, username and password
mandatory
The contract code is the basic identifier of the Acumulus account. The user can use his own combination
of the contractcode, username and password or create a new user for API calls.
email_onerror
non mandatory
If set, errors and warnings raised while importing the invoices, are send to this address by email.
customer
mandatory
The node for all customer data and underlying invoices. Multiple customers are allowed.
type
non mandatory
1 = debtor, 2 = creditor, 3 = debtor/creditor (neutral). Default = 3.
companyname1 and companyname2
non mandatory
Fields for company name and e.g. department.
fullname
non mandatory
Contact person.
salutation
non mandatory
Complete salutation e.g. "Geachte heer Van der Molen" or "Beste Peter" without trailing comma. Default = "Geachte mevrouw/heer".
address1, address2, postalcode
non mandatory
Address fields.
city
non mandatory
City and optional country in capitals (Rotterdam NETHERLANDS).
locationcode
non mandatory
1 = national, 2 = in EU, 3 = outside EU. Default = 1.
countrycode
non mandatory
Use international standard country code (ISO 3166-1) for countries in EU only (NL, DE etc).
vatnumber
non mandatory/mandatory
Vat number should be set for reverse charge of vat (verlegde BTW).
email
non mandatory
Lookup is based on string comparison. If a customer with this email address exists, this customer will be selected. Otherwise a new customer will be added.
overwriteifexists
non mandatory
If a customer is found by it's email address, data can either be left unchanged or overwritten when not NULL.
0 = no update, 1 = overwrite if field is not NULL. Default = 0.
bankaccountnumber
non mandatory
Customer bank account.
mark
non mandatory
Extra label or mark e.g. "BSN: 1234.56.789".
invoice
mandatory
The node for all invoice data and underlying lines. Multiple invoices are allowed.
concept
non mandatory
0 = issued invoice, no concept (default)
1 = concept, no issuing.
If set to 1, the invoice will be saved as a concept instead of an issued invoice.
Although the XML respons returns an invoice number, concepts do not hold invoice numbers until they are saved as an issued invoice and a new invoice number is generated.
number
non mandatory
If ommited, Acumulus will generate a new number following existing invoices in the account.
vattype
non mandatory
1 = national (gewone factuur), 2 = national reverse charge (verlegde BTW),
3 = international reverse charge (intracommunautaire levering), 4 = export outside EU (export), 5 = margin scheme (marge regeling)
Default = 1.
issuedate
non mandatory
Invoice date, if ommited, today is selected. Format: yyyy-mm-dd.
costheading (kostenplaats)
non mandatory
If ommited, first costheading in account will be selected. Lookup on string comparison.
accountnumber
non mandatory
If ommited, first accountnumber in account will be selected. Lookup on string comparison.
paymentstatus
non mandatory
0 = due, 1 = paid. Default = 0.
paymentdate
non mandatory
Date of payment. Default = issue date. Format: yyyy-mm-dd.
description (factuur-toelichting)
non mandatory
Overall description of the invoice, invoice title.
template (factuursjabloon)
non mandatory
If ommited, first template in account will be selected. Lookup on string comparison.
line
mandatory
The node for all product data. Multiple lines are allowed.
itemnumber
non mandatory
Product number, item number (artikelnummer). If set, this number will precede the product description (product).
product
mandatory
Product or service description.
unitprice
mandatory
Unit price without vat. Decimal separator is a point. No thousand separators. 4 decimals precision. E.g. 12.95 or 1200.50 or 12.6495
vatrate
non mandatory
-1 = no vat, 0, 6 or 19. Default = 19
quantity
mandatory
Number of products/services. Decimal separator is a point. No thousand separators. 2 decimals precision. E.g. 1 or 1.5 or 12.64
costprice
non mandatory
Use in case of margin vat (marge-regeling). Decimal separator is a point. No thousand separators. 2 decimals precision. E.g. 12.95 or 1200.50
XML respons
The respons is an XML string containing the invoice number as well as any raised error and warning messages.
<?xml version="1.0" encoding="UTF-8"?>
Respons legend
status
0 = failed, 1 = succes without warnings, 2 = succes with warnings
invoicenumber
Returns the invoice number wether newly generated by Acumulus or echoing the set number.
counterrors and countwarnings
Number of errors and warnings raised during import.
error
Error code and message.
410 get file is empty or does not exist
411 no data
412 invalid XML
420 authentification failed
Errors are fatal and will abort the import process.
warning
Warning code and message.
521 invalid country code, NL will be selected
531 invalid invoice vat type
532 invoice issue date out of range (2000-01-01 - 2030-12-31)
533 invoice costheading not found, first costheading in account will be used
534 invoice account number not found, first account number in account will be used
535 invoice payment status invalid or not set (0 = due, 1 = paid) default 0 is used
536 invoice payment date out of range (2000-01-01 - 2030-12-31), issue date is used
537 invoice template not found, first template in account will be used
541 vat rate invalid or not set (-1 = no vat, 0, 6 or 19) default 19 is used
Warnings will not abort the import process.
Kindly note
Stay tuned!
Change log