InvoiceXpress API

purchase_orders.create

Creates a new purchase order. Also allows to create a new supplier and/or new items in the same request.

If the supplier 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 purchase order on the request body:

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

Example xml to be submitted with the invoice data:

<?xml version="1.0" encoding="UTF-8"?>
<purchase_order>
 <date>19/10/2009</date>
 <due_date>19/10/2009</due_date>
 <loaded_at>16/10/2009</loaded_at>
 <delivery_site>Chiado, Lisboa </delivery_site>
 <observations>Computer processed</observations>
 <supplier>
  <name>Supplier</name>
  <email>supplier@email.com</email>
 </supplier>
 <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>
</purchase_order>

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

Purchase Order 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

Purchase Order 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.

loaded at

Purchase Order loaded at 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.

delivery_site

Purchase order delivery site. Usually a place
Rules: Optional

observations

Purchase Order observations, these will be printed with the document.
Rules: Optional

supplier / name

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

supplier / email

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

supplier / address

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

supplier / postal_code

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

supplier / fiscal_id

Supplier fiscal id.
Rules: Optional.

items

An array of purchase order 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 purchase order is passed back to you in the response.

HTTP: 201 CREATED

<?xml version="1.0" encoding="UTF-8"?>
<purchase_order>
 <id>55</id>
 <status>draft</status>
 <sequence_number>draft</sequence_number>
 <date>19/10/2009</date>
 <due_date>19/10/2009</due_date>
 <loaded_at>16/10/2009</loaded_at>
 <delivery_site>Chiado, Lisboa </delivery_site>
 <observations>Computer Processed</observations>;
 <supplier>
  <id>65</id>
  <name>Supplier</name>
  <email>supplier@email.com</email>
  <address></address>
  <postal_code></postal_code>
  <fiscal_id></fiscal_id>
 </supplier>
 <currency>Euro</currency>
 <items>
  <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>
</purchase_order>

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>Invoice items is invalid</error>
 <error>Supplier 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>