invoices.create

Creates a new invoice. Also allows to create a new client and/or new items in the same request.

If the client name does not exist a new one is created.

If items do not exist with the given names, new ones will be created.

If item name already exists, the item is updated with the new values.

Regarding item taxes, if the tax name is not found, no tax is applyed to that item.

You call this method submitting an HTTP POST request to the following URL with the xml data of the new invoice on the request body:

https://screen-name.invoicexpress.net/invoices.xml

Example xml to be submitted with the invoice data:

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
 <date>19/10/2009</date>
 <due_date>19/10/2009</due_date>
 <reference>123456</reference>
 <observations>Computer processed</observations>
 <retention>5</retention>
 <client>
  <name>Bruce Norris</name>
  <email>foo@bar.com</email>
  <address>Badgad</address>
  <postal_code>120213920139</postal_code>
  <country>Germany</country>
  <fiscal_id>12</fiscal_id>
  <website>www.brucenorris.com</website>
  <phone>2313423424</phone>
  <fax>2313423425</fax>
  <observations>Computer Processed</observations>
 </client>
 <items type="array">
  <item>
   <name>Product 1</name>
   <description>Cleaning product</description>
   <unit_price>10.0</unit_price>
   <quantity>1.0</quantity>
   <unit>unit</unit>
   <discount>10.0</discount>
  </item>
  <item>
   <name>Product 2</name>
   <description>Beauty product</description>
   <unit_price>5.0</unit_price>
   <quantity>1.0</quantity>
   <unit>unit</unit>
   <tax>
    <name>IVA20</name>
   </tax>
   <discount>0.0</discount>
  </item>
 </items>
</invoice>

Parameters

Parameters are the data you will pass with the call.

api_key

Your secret identifier. Your API Key is on Account Overview in the Account section.
Rules: Required

date

Invoice date.
Rules: Required. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.

due date

Invoice date due date.
Rules: Required. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.

reference

Invoice reference, usually a purchase order.
Rules: Optional

observations

Invoice observations, these will be printed with the invoice.
Rules: Optional

retention

Withholding tax percentage (%)
Rules: Optional. Must be a number between 0 and 99.99.

client / name

Client name. If the client doesn’t exist a new one is created. If it exists the remaining client fields will be ignored.
Rules: Required

client / email

Client email.
Rules: Optional. Must be a valid email address ex:foo@bar.com

client / address

Client address, normally used for a company address.
Rules:Optional.

client / postal_code

Client postal code, normally used for a company postal code.
Rules: Optional.

client / country

Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list. Rules: Optional.

client / fiscal_id

Client fiscal id.
Rules: Optional.

client / website

Client website.
Rules: Optional.

client / phone

Client phone number, normally used for a company phone number.
Rules: Optional.

client / fax

Client fax number, normally used for a company fax number.
Rules: Optional.

client / observations

Client default observations, this is added to the observations field on all the invoices sent to this client.
Rules: Optional.

items

An array of invoice items.

If items with the given names do not exist, they are created.
If an item already exists, it is updated with the new values.

Rules: At least one item is required.

item / name

Item name.
Rules: Required. Name must be unique.

item / description

Item description.
Rules: Optional

item / unit_price

Item unit price.
Rules: Required. Must be a number equal or greater than 0.0.

item / quantity

Item quantity.
Rules: Required. Must be a number equal or greater than 0.

item / unit

Item unit of measure.
Rules: Required.

item / discount

The item discount percentage(%).
Rules: Optional. Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.

item / tax

Item tax.
Rules: Optional. If not present no tax is applied to the item

item / tax / name

The item tax name.
Rules: Optional. If not found no tax is applied to the item

Return Values

Success

On success the newly created invoice is passed back to you in the response.

HTTP: 201 CREATED

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
 <id>55</id>
 <status>draft</status>
 <sequence_number>draft</sequence_number>
 <date>19/10/2009</date>
 <due_date>19/10/2009</due_date>
 <reference>123456</reference>
 <observations>Computer Processed</observations>
 <retention>5.0</retention>
 <client>
  <id>65</id>
  <name>Bruce Norris</name>
  <email>foo@bar.com</email>
  <address>Badgad</address>
  <postal_code>120213920139</postal_code>
  <country>Germany</country>
  <fiscal_id>12</fiscal_id>
  <website>www.brucenorris.com</website>
  <phone>2313423424</phone>
  <fax>2313423425</fax>
  <preferred_contact>
    <name>Bruce Norris</name>
    <email>foo@bar.com</email>
    <phone>2233442233</phone>
  </preferred_contact>
  <observations>Computer Processed</observations>
  <send_options>1</send_options>
 </client>
 <currency>Euro</currency>
 <items type="array">
  <item>
   <id>19</id>
   <name>Product 1</name>
   <description>Cleaning product</description>
   <unit_price>10.0</unit_price>
   <quantity>1.0</quantity>
   <unit>unit</unit>
   <tax>
    <name></name>
    <value>0.0</value>
   </tax>
   <discount>10.0</discount>
  </item>
  <item>
   <id>20</id>
   <name>Product 2</name>
   <description>Product for beauty</description>
   <unit_price>5.0</unit_price>
   <quantity>1.0</quantity>
   <unit>unit</unit>
   <tax>
    <id>19</id>
    <name>IVA20</name>
    <value>20.0</value>
   </tax>
   <discount>0.0</discount>
  </item>
 </items>
 <sum>15.0</sum>
 <discount>1.0</discount>
 <before_taxes>14.0</before_taxes>
 <taxes>1.0</taxes>
 <total>14.3</total>
</invoice>

Error

HTTP: 401 Access denied
The API Key parameter is missing or incorrect.

HTTP: 422 Unprocessable Entity
Some parameters were incorrect.

Possible errors:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Your current plan does not allow you to do this</error>
</errors>

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Retention must be a number between 0 and 99.99</error>
 <error>Invoice items is invalid</error>
 <error>Invoice items is invalid</error>
 <error>Client is invalid</error>
 <error>Due date must be later than date</error>
 <error>email must be an email address</error>
 <error>discount is not a number</error>
 <error>quantity must be a number greater than 0</error>
 <error>unit_price must be a number</error>
 <error>Unit kg is not included in the list of accepted units</error>
 <error>Unit  is not included in the list of accepted units</error>
</errors>

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Items element should be of type array</error>
</errors>

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Country Germani was not found</error>
</errors>