API-v1

Application Programming Interface

InvoiceXpress Documentation



Update


debit-notes.update

Updates a debit-note.

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

If the item does not exist with the given name, a new one will be created. If the item exists it will be updated with the new values. Be careful when updating the document items, any missing items from the original document will be deleted.

Usage

You call this method by submitting a HTTP PUT request to the following URL with the debit-note data on XML format in the request body:

https://{account-name}.app.invoicexpress.com/debit_notes/{debit-note-id}.xml
Header

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

Body
<debit_note>
 <date>11/05/2015</date>
 <due_date>15/05/2015</due_date>
 <client>
  <name>Ricardo Pereira</name>
 </client>
 <items type="array">
  <item>
   <name>MacBook Pro</name>
   <description></description>
   <unit_price>1000.0000</unit_price>
   <quantity>1.0</quantity>
  </item>
 </items>
</debit_note>

Parameters

Parameter Required Description
api_key Yes Your secret identifier. You can find your API Key under Account >> API in the Account section.
owner_invoice_id No The (owner) invoice associated to this debit-note.
debit-note-id Yes ID of the debit-note to update.
date Yes The debit-note 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 The debit-note due date. Must be in format dd/mm/yyyy ex: 03/12/2010. If format is invalid, date will be set to current date.
reference No The debit-note purchase order reference field.
observations No debit-note observations, these will be printed with the debit-note.
retention No Withholding tax percentage (%). Must be a number between 0 and 99.99.
retention No Withholding tax percentage (%). Must be a number between 0 and 99.99.
tax_exemption Depends Portuguese IVA exemption code. Required for portuguese accounts on debit-note with IVA exempt items (0%). Must be one of the following: M01, M02, M03, M04, M05, M06, M07, M08, M09, M10, M11, M12, M13, M14, M15, M16, M99. See the table "IVA Exemption Codes" for more details.
sequence_id No Id of the sequence you want to use with this debit-note. If missing, the default sequence will be used.
client / name Yes The client that the invoice is to. If the client doesn’t exist a new one is created. If it exists the remaining client fields will be ignored.
client / code Yes The client unique code that the invoice is to. If the client doesn’t exist a new one is created. If it exists the remaining client fields will be ignored.
client / email No Client email address. Must be a valid email address ex: foo@bar.com
client / address No Client company address.
client / city No Client's city.
client / postal_code No Client's postal code for it's company address.
client / country No Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the Appendix of this Documentation.
client / fiscal_id No The client fiscal ID (Número de Contribuinte)
client / website No The client web address
client / phone No The client phone number
client / fax No The client fax number
client / observations No The client default observations. This is added to the observations field of all the debit-notes sent to this client
items Yes 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. At least one is required.
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 no tax is applied to the item
item / tax / name No The tax name to be used on this item line. If not found no tax is applied to the line item

Return Values

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

Success
HTTP: 200 OK
Error
Code Description
HTTP: 401 Access denied The API Key parameter is missing or is incorrectly entered.
HTTP: 404 Not Found The supplied {debit-note-id} doesn't match any existing invoice.
HTTP: 422 Unprocessable Entity Some parameters sent were incorrect. See below for possible errors.

Possible Errors for HTTP: 422

<errors>
 <error>Retention must be a number between 0 and 99.99</error>
 <error>debitNote 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>
</errors>
<errors>
 <error>DebitNote has been settled so can't be changed anymore.</error>
</errors>
<errors>
  <error>Country Germani was not found</error>
</errors>

Engenharia e Design ao seu serviço!

Uma equipa de Engenharia e Produto que pensam, desenham e executam em detalhe cada pormenor da experiência dos utilizadores.

Uma equipa ao seu dispor que trabalha diariamente para si.

Conhecer o InvoiceXpress