invoices.update
Updates an invoice. It also allows you to create a new client and/or items in the same request.
If the client name does not exist a new client is created.
Regarding item taxes, if the tax name is not found, no tax is applyed to that item.
If items supplied are valid, the new ones will replace the old ones. Meaning, if update succeeds, all invoice items previously created will be replaced by the ones supplied on the request XML file.
You call this method by submitting a HTTP PUT request to the following URL with the invoice updates on xml format in the request body:
Example xml to be submitted with the updated 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. You find your API Key under Account Overview in the Account section.
Rules: Required
invoice-id
Id of the invoice to update.
Rules: Required
date
Invoice date.
Rules: Optional. The date format should be dd/mm/yyyy. Ex: 01/09/2010
due date
Invoice date due date.
Rules: Optional. The date format should be dd/mm/yyyy. Ex: 01/09/2010
reference
Reference, usually a purchase order.
Rules: Optional
observations
Invoice observations, these will be printed with the invoice.
Rules: Optional
retention
Withholding tax (%)
Rules: Optional
client / name
Client name. If the client doesn’t exist a new one is created. If it exists the remaining client fields are 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.
When updating an invoice you must send all items, items from the original invoice will be deleted.
If no item with the given name exists a new item is created.
If the item name already exists it is updated with the new values.
Rules: At least one item is required.
item / name
Item name.
Rules: Required
item / description
Item description.
Rules: Optional
item / unit_price
Item unit price.
Rules: Required. Needs to be greater than 0.0.
item / quantity
Item quantity.
Rules: Required. Needs to be greater than 0.0.
item / unit
Item unit of measure.
Rules: Required.
item / discount
The item discount.
Rules: Optional. Defaults to 0.0. If present needs to be greater or equal than 0.0.
item / tax
Item tax.
Rules: Optional. If not present no tax is applied to the item
item / tax / name
Item tax name.
Rules: Optional. If not found no tax is applied to the item
Return Values
This is the result that will be passed back to you when you have sent a call.
Success
Error
The API Key parameter is missing or is incorrectly entered.
The :invoice-id supplied doesn’t match any existing invoice.
Some of the parameters sent were incorrect.
Possible 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> <?xml version="1.0" encoding="UTF-8"?> <errors> <error>Invoice has been settled so cant be changed anymore.</error> </errors> <?xml version="1.0" encoding="UTF-8"?> <errors> <error>Country Germani was not found</error> </errors>