API - Invoice Add

Importing debtor invoices into Acumulus - Facturen importeren in Acumulus


Resource:
/acumulus/stable/invoices/invoice_add.php
Since API:
Authentication:
API user
Communication:
Basic submit, including below structure


Submit

Full XML Submit Structure.
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"?>
<myxml>
    <format></format>
    <testmode></testmode>
    <contract>
        <contractcode></contractcode>
        <username></username>
        <password></password>
        <emailonerror></emailonerror>
        <emailonwarning></emailonwarning>
    </contract>
    <customer>
        <type></type>
        <contactid></contactid>
        <contactyourid></contactyourid>
        <contactstatus></contactstatus>
        <companyname1></companyname1>
        <companyname2></companyname2>
        <fullname></fullname>
        <salutation></salutation>
        <address1></address1>
        <address2></address2>
        <postalcode></postalcode>
        <city></city>
        <country></country>
        <countrycode></countrycode>
        <vatnumber></vatnumber>
        <telephone></telephone>
        <fax></fax>
        <email></email>
        <overwriteifexists></overwriteifexists>
        <bankaccountnumber></bankaccountnumber>
        <mark></mark>
        <disableduplicates></disableduplicates>
        <invoice>
            <concept></concept>
            <concepttype></concepttype>
            <number></number>
            <vattype></vattype>
            <issuedate></issuedate>
            <costcenter></costcenter>
            <accountnumber></accountnumber>
            <paymentstatus></paymentstatus>
            <paymentdate></paymentdate>
            <description></description>
            <descriptiontext></descriptiontext>
            <template></template>
            <invoicenotes></invoicenotes>
            <line>
                <itemnumber></itemnumber>
                <product></product>
                <nature></nature>
                <unitprice></unitprice>
                <vatrate></vatrate>
                <quantity></quantity>
                <costprice></costprice>
            </line>                    
            <emailaspdf>
                <emailto></emailto>
                <emailbcc></emailbcc>
                <emailfrom></emailfrom>
                <subject></subject>
                <message></message>
                <confirmreading></confirmreading>
            </emailaspdf>
        </invoice>
    </customer>
</myxml>

Please note that only contractcode, username, password and format can be supplied using GET/POST parameters.

type non mandatory

Option
Description
1
Debtor
2
Creditor
3
Debtor/Creditor (neutral) (DEFAULT)

contactid non mandatory
When a valid contactid is provided the customer details from this specific contactid will be used for creating the invoice. Has a higher priority over the email tag when trying to match against a specific contact.

contactyourid non mandatory
Additional identifier for your contact. Does not need to be unique and can be made available on the invoice through a setting in the invoice templates.

contactstatus non mandatory

Option
Description
0
Not active / disabled
1
Active (DEFAULT)

fullname non mandatory
Contact person.

companyname1 non mandatory
Field for company name and e.g. department.

companyname2 non mandatory
Additional fields for company name and e.g. department.

salutation non mandatory
Complete salutation e.g. "Geachte heer van der Molen" or "Beste Peter" without trailing comma. When not set it defaults to content set in the contact details in Acumulus or when those details are not set to: "Geachte mevrouw/heer".

address1 non mandatory
Address field.

address2 non mandatory
Address field.

postalcode non mandatory
Address field.

city non mandatory
City.

city non mandatory
City and optional country in capitals (Amsterdam NETHERLANDS).

countrycode mandatory
Use international standard country code (ISO 3166-1 alpha 2).

country non mandatory
Country. Leave empty when you do not want the country to appear on the invoice.

IN DEVELOPMENT: countryautoname non mandatory

Option
Description
0
None (DEFAULT)
1
Automatic prefill of countryname based on supplied countrycode<
2
Automatic prefill of countryname based on supplied countrycode. Including Nederland

vatnumber non mandatory/mandatory
VAT-number is mandatory when trying to set reverse charge of VAT. Also known as "verlegde BTW".

telephone non mandatory
Customer contact telephone number.

fax non mandatory
Customer contact fax number.

email non mandatory
Lookup is based on string comparison. If a customer with this email address exists, this customer will be selected. When multiple customers with the same email address are found only the most recent added contact is used. When no matches are made a new customer will be added as part of the invoice add transaction. Setting can be overruled when a matching contactid tag is provided.

overwriteifexists non mandatory
If a customer match has been made using the email address as an identifier, all customer details can be overwritten with the information provided within the request. Even if this means that some fields will be cleared.

Option
Description
0
No update made (DEFAULT)
1
Overwrite all customer contact details

bankaccountnumber non mandatory
Customer bank account or IBAN number.

mark non mandatory
Extra label or mark e.g. "BSN: 1234.56.789".

disableduplicates non mandatory
Useful for disabling older instances of a contact when multiple contacts match the provided email.

Option
Description
0
Leave older duplicate contacts as is (DEFAULT)
1
Mark duplicate contacts as disabled

invoice mandatory
The node for all invoice data and underlying lines. Only a single invoice section is allowed.

concept non mandatory
When set to 1, the invoice will be saved as a concept instead of an issued invoice. Although the XML response 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.

Option
Description
0
Issue invoice, no concept (DEFAULT)
1
Concept, no issuing

Please note that no true invoice will be generated and that no invoice-email will be send out with the concept tag is set to 1.

concepttype non mandatory
Optional value to indicate the type of concept. Please see the concepttype picklist for available values.

number non mandatory
When omitted, Acumulus will automatically calculate a new number following existing invoices in the account.

vattype non mandatory
A single digit indicating the vattype of the invoice. When using vattype 6(foreign vat) both the product vatrate and the countrycode become mandatory.

Option
Description
Description
 
1
National
Gewone nationale factuur
DEFAULT
2
National reverse charge
Verlegde BTW binnen Nederland
 
3
International reverse charge
BTW-verlegd naar ondernemer in de EU. Een intracommunautaire levering.
 
4
Export outside EU (export)
Een factuur voor goederen buiten de EU
 
5
Margin scheme
Marge regeling voor 2e-hands producten
 
6
Foreign VAT
Buitenlandse BTW voor electronische diensten aan particulieren in de EU. Usage of countrycode mandatory
 

See the Acumulus Wiki for more information on Acumulus vattypes.

issuedate non mandatory
Invoice date, if omitted, today is selected. Format: yyyy-mm-dd.

costcenter (kostenplaats) non mandatory
The value must either provided as an numeric identifier (when using the picklist feature) or as the exact name of the costcenter. Please note that only references to active costcenters are allowed. When omitted, or when no match has been made possible, the first available costcenter in the contract will be selected.

A list of available costcenters can be retrieved with a special special picklist API call.

accountnumber non mandatory
The accountnumber correlates to the bankaccountnumber of the Acumulus contract owner. The value is either provided as an numeric identifier (when using the picklist feature) or as a string. We suggest to use the numeric identifier as string support is deprecated and will be removed in the future. When omitted, or when no match has been made possible, the first available accountnumber in the contract will be selected. Please note that only references to active accountnumbers are allowed. When the provided or determined accountnumber has been marked as inactive it will be reactivated.

A list of available accountnumbers can be retrieved with a special picklist API call.

paymentstatus non mandatory

Option
Description
1
Due (DEFAULT)
2
Paid

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.

descriptiontext (uitgebreide factuur-toelichting) non mandatory
Multiline field for extended description of the invoice. Content will appear on invoice and associated emails. Use \n for newlines. Tabs are not supported.

template (factuursjabloon) non mandatory
The value must either provided as an numeric identifier (when using the picklist feature) or as the exact name of the template. When omitted, or when no match has been made possible, the first available template in the contract will be selected.

A list of available templates can be retrieved with a special picklist API call.

invoicenotes non mandatory
Multiline field for additional remarks. Use \n for newlines and \t for tabs. Contents is placed in notes/comments section of the invoice. Content will not appear on the actual invoice or associated emails.

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). Please note that there is (currently) no explicit relation with the available product numbers in Acumulus.

product non mandatory
Product or service description. Although not mandatory, you are strongly advised to set this. Defaults to "PRODUCT DESCRIPTION NOT SET".

nature non mandatory

Option
 
Product
DEFAULT
Service
 

unitprice non 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. Will be rounded if provided with more than 4 decimals.

vatrate mandatory
Applicable vatrate for the product. Defaults to "21".

Option
Description
-1
No VAT
0
0% VAT
6
6% VAT
..
..% VAT
21
21% VAT (DEFAULT)
25%
25% VAT

When creating invoices with foreign vat applied a valid rate for the associated country will need to be supplied. When no correct vatrate is found for the provided country the highest available vatrate will be used. See also the Vatinfo lookup API

quantity non 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. Default is 1.

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

emailaspdf non mandatory
Imported invoices can be send as pdf file using email.

emailto mandatory/non mandatory
Mandatory when using emailaspdf. Use valid email addresses. Muliple addresses can be used when separated with a comma or semicolon. If emailto is not set, the email option will be skipped. Addresses will be checked on format. Inconsistent or incorrect addresses will raise a warning and no mail will be sent. Regular processing of the invoice will continue.

emailbcc non mandatory
Use valid email addresses. Muliple addresses can be used when separated with a comma or semicolon. If emailto is not set, the emailbcc will be ignored and skipped. Addresses will be checked on format. Inconsistent or incorrect addresses will raise a warning and no mail will be sent. Regular processing of the invoice will continue. When emailto is set and emailbcc is not set the emailbcc settings from the invoice template will be used as a fall-back for emailbcc.

emailfrom non mandatory
Use a single valid emailaddress. If omitted, the email address of the invoice template, with fallback to the account owner will be used. Most pretty results are obtained when using fully configured invoice templates in Acumulus and leaving this option empty (recommended).

subject non mandatory
If omitted or left empty, the subject will be: Factuur [number] [description]

message non mandatory
Mileage may vary when trying to submit multiple lines. Use \n when doing so. If omitted, the email text composed in the template will be used (recommended).

confirmreading non mandatory
Ask the recipient to confirm the delivery of the email message.

Option
Description
0
Do not ask for confirmation (DEFAULT)
1
Ask for confirmation

Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <invoice>
        <invoicenumber></invoicenumber>
        <token></token>
        <entryid></entryid>
    </invoice>
</response>
</xml>

Plus the default error and warning-reporting as described in the global legend page.

invoicenumber
Returns the invoice number. Whether newly generated by Acumulus or echoing the set number.

token
Unique 32-character public identifier(hash). One can publicly retrieve an invoice as PDF using this token en the Invoice Get API-call. (get.php?token=[token])

entryid
The entryid, also known as boekstuknummer assigned to the newly added invoice.