debit_notes.create

InvoiceXpress API

Creates a new debit note

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 applied to that item.

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

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

Example xml to be submitted with the invoice data:

<?xml version="1.0" encoding="UTF-8"?>
<debit_note>
 <date>19/10/2009</date>
 <due_date>19/10/2009</due_date>
 <reference>123456</reference>
 <observations>Computer processed</observations>
 <retention>5</retention>
 <client>
  <name>Client</name>
  <code>Code</code>
  <email>client@email.com</email>
 </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>
</debit_note>

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

Debit note 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

Debit note 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 / code

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

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 / fiscal_id

Client fiscal id.
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 debit note is passed back to you in the response.

HTTP: 201 CREATED

<?xml version="1.0" encoding="UTF-8"?>
<debit_note>
 <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>Client</name>
  <email>client@email.com</email>
  <address></address>
  <postal_code></postal_code>
  <fiscal_id></fiscal_id>
 </client>
 <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>
</debit_note>

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>Client is invalid</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>

InvoiceXpress Software Certificado.

InvoiceXpress API