API - Invoice Add

Importing debtor invoices into Acumulus - Facturen importeren in Acumulus


Resource:
/acumulus/stable/invoices/invoice_add.php
Since API:
Available for authenticated:
API invoerder
Available for authenticated:
API gebruiker
Available for authenticated:
API beheerder
Communication:
Basic submit, including below structure

Support voor testmode :

Submit

<?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>
        <contactid></contactid>
        <type></type>
        <vattypeid></vattypeid>
        <contactyourid></contactyourid>
        <contactstatus></contactstatus>
        <companyname1></companyname1>
        <companyname2></companyname2>
        <fullname></fullname>
        <salutation></salutation>
        <address1></address1>
        <address2></address2>
        <postalcode></postalcode>
        <city></city>
        <country></country>
        <countrycode></countrycode>
        <countryautoname></countryautoname>
        <countryautonamelang></countryautonamelang>
 
        <altcompanyname1></altcompanyname1>
        <altcompanyname2></altcompanyname2>
        <altfullname></altfullname>
        <altaddress1></altaddress1>
        <altaddress2></altaddress2>
        <altpostalcode></altpostalcode>
        <altcity></altcity>
        <altcountry></altcountry>
        <altcountrycode></altcountrycode>
        <altcountryautoname></altcountryautoname>
        <altcountryautonamelang></altcountryautonamelang>
 
        <website></website>
        <vatnumber></vatnumber>
        <telephone></telephone>
        <telephone2></telephone2>
        <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>                    
            <line>
                ...
            </line>
            <line>
                ...
            </line>
 
            <emailaspdf>
                <emailto></emailto>
                <emailbcc></emailbcc>
                <emailfrom></emailfrom>
                <subject></subject>
                <message></message>
                <confirmreading></confirmreading>
            </emailaspdf>
 
        </invoice>
    </customer>
</myxml>


<customer> mandatory section

contactid
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.

type
Option
Description
1
Debtor
2
Creditor
3
Debtor/Creditor (neutral) [default]

vattypeid
vattypeid
description
description
1 [default]
Private and/or VAT exempt
Particulier en/of btw-vrijgesteld
2
Business VAT taxable
Zakelijk btw-plichtig

contactyourid
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
Option
Description
0
Not active / disabled
1
Active [default]

fullname
Contact person.

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

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

salutation
Complete salutation e.g. "Geachte heer van der Molen" or "Dear 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
Address field.

address2

postalcode

city

countrycode
Use international standard country code (ISO 3166-1 alpha 2). Defaults to "NL".

country
Country. Provide XML-node, but leave empty when you do not want the country to appear on the invoice.

CURRENTLY IN DEVELOPMENT: countryautoname
Automatically set country for contact. Useful for spelling-corrections in country naming. Will overwrite provided country when set.
Option
Description
0
No automatic naming. Leave provided or omitted country as is. [default]
1
Automatic naming of country based on supplied countrycode. Excluding Nederland.
2
Automatic naming of country based on supplied countrycode. Including Nederland

countryautonamelang
Language selection when using countryautoname.
Option
Description
nl
Use Dutch names for countries when using countryautoname [default]

altfullname
Applies to 2nd/alt address. Contact person.

altcompanyname1
Applies to 2nd/alt address. Field for company name and e.g. department.

altcompanyname2
Applies to 2nd/alt address. Additional fields for company name and e.g. department.

altaddress1
Applies to 2nd/alt address. Address field.

altaddress2
Applies to 2nd/alt address.

altpostalcode
Applies to 2nd/alt address.

altcity
Applies to 2nd/alt address.

altcountrycode
Applies to 2nd/alt address. Use international standard (ISO 3166-1 alpha 2). Defaults to "NL".

altcountry
Applies to 2nd/alt address. Country. Provide XML-node, but leave empty when you do not want the altcountry to appear on the invoice.

CURRENTLY IN DEVELOPMENT: altcountryautoname
Applies to 2nd/alt address. Automatically set country for contact. Useful for spelling-corrections in altcountry naming. Will overwrite provided altcountry when set.
Option
Description
0
No automatic naming. Leave provided or omitted country as is. [default]
1
Automatic naming of country based on supplied countrycode. Excluding Nederland.
2
Automatic naming of country based on supplied countrycode. Including Nederland

altcountryautonamelang
Applies to 2nd/alt address. Language selection when using countryautoname.
Option
Description
nl
Use Dutch names for countries when using countryautoname [default]

CURRENTLY IN DEVELOPMENT: website
Customer contact web-reference.

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

telephone
Customer contact telephone number.

CURRENTLY IN DEVELOPMENT: telephone2
Customer contact second telephone number.

fax
Customer contact fax number.

email
Note about email
The customer email address is one of two core identifiers for assigning the invoice.
Another core identifier for the assignment of the invoice is the contactid xml-node.
When provided, the contactid trumps the email address in priority.

If a customer with this email address already exists in the administration, the provided
address will be used to determine the correct customer contact identifier.

When multiple contacts with the same email address are found the most recent added is used.

A new customer contact will be created with no matches are made and no another core identifier
is available. This new added customer will be used to assign the invoice to.

overwriteifexists
Update contact information as part of the proces.
Note about overwriteifexists
For existing contacts, based on contactid or email only sumitted xml-nodes will be used
to overwrite or clear known values. Provide an empty node to explicitly clear a value.
Option
Description
0
No update made [default]
1
Update customer contact details

bankaccountnumber
Customer bank account or IBAN.

mark
Extra label or mark. I.e. "Servicecode: 1234", "deliver to attic". Will be included on the relevant documents like invoice, reminders and delivery notes.

disableduplicates
Allows for disabling instances of a contact when multiple contacts match the provided email.

Option
Description
0
Leave contacts with similar email adresses as is [default]
1
Mark duplicate contacts as disabled


<invoice> mandatory section

concept
Invoice wille be save as concept/draft when set to 1. Although the API response returns a preliminairy invoice number, concept/draft entries will only apply a real, usually newly generated, invoice number when made final.

Option
Description
0
Issue invoice, no concept [default]
1
Concept or draft invoice. No definitive 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
Optional value to indicate the type of concept. Please see the concepttype picklist for available values.

number
Integer. When omitted (preferred) or set to 0 Acumulus will automatically calculate the next number following existing invoices for the year of the issuedate. Can only be prefixed and suffixed with alphanumeric strings through the applicable invoice template.

vattype
Integer indicating the vattype of the invoice. When using vattype 6(foreign vat) both the product vatrate and the countrycode become mandatory.
Please see the Acumulus manual for more information on Acumulus vattypes.
Option
Description
Description
1 [default]
National
Gewone nationale factuur
2
National reverse charge
Verlegde BTW binnen Nederland
3
International reverse charge
Intracommunautaire levering.
4
Export outside EU (export)
Goederen buiten de EU
5
Margin scheme
Marge regeling (2e-hands)
6
European VAT
Europese BTW

issuedate
Invoice date. Format: YYYY-MM-DD. When omitted, current day is applied.

costcenter (kostenplaats)
The value must be provided as an numeric identifier. Matches based on the exact name of the costcenter are deprecated and will be phased out. Please note that only references to active costcenters are allowed. When omitted, or when no match has been made possible, the first available active costcenter will be used.
Please note the special costcenter picklist API. and be advised that costcenterid in the picklist should be used as identifier for "costcenter" in this invoice add API.

accountnumber
The value must be provided as an numeric identifier. Matches based on the exact name of the accountnumber are deprecated and will be phased out. When omitted, or when no match has been made possible, the first available active accountnumber will be used. When the accountnumber has been marked as inactive it will be reactivated.
Please note the special accounts picklist API and be advised that accountid in the picklist should be used as identifier for "accountnumber" in this invoice add API.

paymentstatus
Status of payment.
Option
Description
Omschrijving
1
Due [default]
Niet betaald [default]
2
Paid
Voldaan/betaald

paymentdate
Date of payment. Default is issue date. Format: YYYY-MM-DD.

description (factuur-toelichting)
Single line indicating overall description of the invoice, invoice title.

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

template (factuursjabloon)
The value must be provided as an numeric identifier. Matches based on the exact name of the template are deprecated and will be phased out. When omitted, or when no match has been made possible, the first available active template will be used.
Please note the special invoice templates picklist API and be advised that invoicetemplateid in the picklist should be used as identifier for "template" in this invoice add API.

invoicenotes
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. Notes will be for references in the entry.

<line> mandatory section(s)

Data node for invoice lines / product data. Multiple occurences supported.

itemnumber
Product number, item number (artikelnummer). Will precede the product description when set.

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

nature
Option
 
Product
DEFAULT
Service
 

unitprice
Price without VAT for a single item.
  • 4 decimal precision.
  • Automaticaly rounded when more than 4 decimals.
  • Decimal separator is a point.
  • No thousand separators.
  • Defaults to 0.0000.

vatrate
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 using foreign/EU vat, a valid rate for the associated country is mandatory. When no correct vatrate is found for the provided country the highest available vatrate will be used. See also the Vatinfo lookup API

quantity
  • 2 decimal precision.
  • Automaticaly rounded when more than 2 decimals.
  • Decimal separator is a point.
  • No thousand separators.
  • Defaults to 1.

costprice
Total costprice for line (full quantity). Mandatory when using margin scheme (marge-regeling).
  • costprice assumes total costprice for line (full quantity).
  • 4 decimal precision.
  • Automaticaly rounded when more than 4 decimals.
  • Decimal separator is a point.
  • No thousand separators.
  • Defaults to 0 for margin scheme or empty otherwise.

<emailaspdf>

Imported invoices can be direclty send as PDF file using email. Only one instance of emailaspdf is supported.

emailto
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
Muliple addresses can be used when separated with a comma or semicolon. When emailbcc is not set the emailbcc settings from the invoice template will be used as fall-back.

emailfrom
Use a single valid email address. When ommitted, 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
If omitted or left empty, the subject will be: Factuur [number] [description]

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

confirmreading
Ask the recipient to confirm the delivery of the email message. Most people find this annoying.
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>
        <conceptid></conceptid>
    </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.

conceptid
The conceptid is a unique numeric reference for an invoice added as concept.