API

Application Programming Interface

InvoiceXpress Documentation



Create


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, the default tax is applied to that item.

You call this method by submitting an HTTP POST request to the following URL with the XML data of the new purchase order on the request body:

https://{account-name}.app.invoicexpress.com/purchase_orders.xml
Header

Content-Type: application/xml; charset=utf-8

Body
<purchase_order>
 <date>05/05/2015</date>
 <due_date>05/05/2015</due_date>
 <loaded_at>05/05/2015</loaded_at>
 <delivery_site>Chiado, Lisboa</delivery_site>
 <observations>Computer processed</observations>
 <supplier>
  <name>Supplier</name>
  <code>Code</code>
  <email>someone@example.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

Parameter Required Description
api_key Yes Your secret identifier. You can find your API Key under Account >> API in the Account section.
date Yes Purchase Order date. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.
due date Yes Purchase Order due date. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.
loaded at Yes Purchase Order loaded at date. Must be in format dd/mm/yyyy ex.: 03/12/2010. If format is invalid, date will be set to current date.
delivery_site Optional Purchase Order observations, these will be printed with the document.
observations Optional Purchase Order observations, these will be printed with the document.
supplier / name Yes Supplier name. If the supplier doesn’t exist a new one is created. If it exists the remaining supplier fields will be ignored.
supplier / code Optional Supplier code.
supplier / email Optional Supplier email.
supplier / address Optional Supplier address, normally used for a company address.
supplier / city Optional Supplier city.
supplier / postal_code Optional Supplier postal code, normally used for a company postal code.
supplier / fiscal_id Optional Supplier fiscal id.
items Yes 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.
item / name Yes Name of the item. Must be unique.
item / description Yes Item’s description
item / unit_price Yes Item’s unit price. Must be a number equal or greater than 0.0.
item / quantity Yes Quantity. Must be a number equal or greater than 0.
item / unit No The item unit of measure
item / discount No The item discount percentage(%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.
item / tax No The tax applied to the item line. If not present the default tax is applied to the item
item / tax / name No The tax name to be used on this item line. If not found the default tax is applied to the line item

Return Values

These are the results that will be returned on success and error.

Success
HTTP: 201 CREATED
<purchase_order>
  <id>541083</id>
  <status>draft</status>
  <archived>false</archived>
  <type>PurchaseOrder</type>
  <sequence_number>draft</sequence_number>
  <date>05/05/2015</date>
  <due_date>05/05/2015</due_date>
  <reference></reference>
  <observations>Computer processed</observations>
  <retention></retention>
  <permalink>http://www.app.invoicexpress.com/documents/54108375763e7db8570afa2589dbd2cde9d7ae73b60e54</permalink>
  <client>
    <id>233428</id>
    <name>Ricardo Pereira</name>
    <code>123</code>
    <email>someone@example.com</email>
    <address>Lisbon</address>
    <postal_code>1202-456</postal_code>
    <country>Portugal</country>
    <fiscal_id>508043456</fiscal_id>
    <website>www.invoicexpress.com</website>
    <phone>2313423424</phone>
    <fax>2313423425</fax>
    <observations>Computer Processed</observations>
  </client>
  <currency>Euro</currency>
  <items type="array">
    <item>
      <name>Product 1</name>
      <description>Cleaning product</description>
      <unit_price>10.0</unit_price>
      <unit>unit</unit>
      <quantity>1.0</quantity>
      <tax>
        <id>31321</id>
        <name>IVA23</name>
        <value>23.0</value>
      </tax>
      <discount>10.0</discount>
      <subtotal>9.0</subtotal>
      <tax_amount>2.07</tax_amount>
      <discount_amount>1.0</discount_amount>
      <total>11.07</total>
    </item>
    <item>
      <name>Product 2</name>
      <description>Beauty product</description>
      <unit_price>5.0</unit_price>
      <unit>unit</unit>
      <quantity>1.0</quantity>
      <tax>
        <id>31454</id>
        <name>IVA20</name>
        <value>20.0</value>
      </tax>
      <discount>0.0</discount>
      <subtotal>5.0</subtotal>
      <tax_amount>1.0</tax_amount>
      <discount_amount>0.0</discount_amount>
      <total>6.0</total>
    </item>
  </items>
  <sum>15.0</sum>
  <discount>1.0</discount>
  <before_taxes>14.0</before_taxes>
  <taxes>3.07</taxes>
  <total>17.07</total>
</purchase_order>
Error

In case of error it will return:

Code Description
HTTP: 401 Access denied The API Key parameter is missing or is incorrectly entered.
HTTP: 422 Unprocessable Entity Some parameters were incorrect.

Possible errors for HTTP: 422

<errors>
 <error>Your current plan does not allow you to do this</error>
</errors>
<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>
</errors>