API

Application Programming Interface

InvoiceXpress Documentation



Create


proformas.create

Creates a new proforma.

Creating new clients or items along with the proforma

This method also allows to create a new client and/or new items in the same request with the following behavior:

  • 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.

Taxes

Regarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the proforma contains exempt items (IVA 0%)

Usage

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

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

XML example to be submitted with proforma data:

Header

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

Body
<proforma>
 <date>07/05/2015</date>
 <due_date>08/05/2015</due_date>
 <client>
  <name>Ricardo Pereira</name>
  <code>100</code>
 </client>
 <items type="array">
  <item>
   <name>Product 1</name>
   <description>Cleaning product</description>
   <unit_price>10.0</unit_price>
   <quantity>1.0</quantity>
  </item>
  <item>
   <name>Product 2</name>
   <description>Beauty product</description>
   <unit_price>5.0</unit_price>
   <quantity>1.0</quantity>
   <tax>
    <name>IVA23</name>
   </tax>
  </item>
 </items>
</proforma>

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 The proforma date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date.
due date Yes The proforma due date. Must be in format dd/mm/yyyy ex.: 03/12/2015. If format is invalid, date will be set to current date.
reference No The proforma purchase order reference field.
observations No Proforma observations, these will be printed with the proforma.
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 proformas 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” below for more details.
sequence_id No Id of the sequence you want to use with this proforma. If missing, the default sequence will be used.
manual_sequence_number Depends Required for non portuguese accounts with manual sequence numbering.
client / name Yes The proforma’s client. 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’s unique code. 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 proformas sent to this client
items Yes An array of proforma 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 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
mb_reference No Generates a Multibanco Reference after you finalize your proforma. This option is only available for Portuguese Accounts. You must have the feature enabled on your account first. Must be a number equal to either 1 or 0.
auto_add_related_document No Send invoice to client after payment. This option is only available for accounts with payment services configurated. Must be a number equal to either 1 or 0.

IVA Exemption Codes

Code Description on the proforma Where does it apply?
M01 Artigo 16.º n.º 6 alínea c) do CIVA Artigo 16.º n.º 6 alínea c) do CIVA
M02 Artigo 6.º do Decreto‐Lei n.º 198/90, de 19 de Junho Artigo 6.º do Decreto‐Lei n.º 198/90, de 19 de Junho
M03 Exigibilidade de caixa Decreto‐Lei n.º 204/97, de 9 de Agosto; Decreto‐Lei n.º 418/99, de 21 de Outubro; Lei n.º 15/2009, de 1 de Abril;
M04 Isento Artigo 13.º do CIVA Artigo 13.º do CIVA
M05 Isento Artigo 14.º do CIVA Artigo 14.º do CIVA
M06 Isento Artigo 15.º do CIVA Artigo 15.º do CIVA
M07 Isento Artigo 9.º do CIVA Artigo 9.º do CIVA
M08 IVA – Autoliquidação Artigo 2.º n.º 1 alínea i) do CIVA; Artigo 2.º n.º 1 alínea j) do CIVA; Artigo 6.º do CIVA; Artigo 2.º n.º 1 alínea l) do CIVA; Decreto‐Lei n.º 21/2007, de 29 de Janeiro; Decreto‐Lei n.º 362/99, de 16 de Setembro;
M09 IVA ‐ não confere direito a dedução Artigo 60.º CIVA; Artigo 72.º n.º 4 do CIVA;
M10 IVA – Regime de isenção Artigo 53.ºdo CIVA
M11 Regime particular do tabaco Decreto-Lei n.º 346/85, de 23 de Agosto
M12 Regime da margem de lucro – Agências de Viagens Decreto‐Lei n.º 221/85, de 3 de Julho
M13 Regime da margem de lucro – Bens em segunda mão Decreto‐Lei n.º 199/96, de 18 de Outubro
M14 Regime da margem de lucro – Objetos de arte Decreto‐Lei n.º 199/96, de 18 de Outubro
M15 Regime da margem de lucro – Objetos de coleção e antiguidades Decreto‐Lei n.º 199/96, de 18 de Outubro
M16 Isento Artigo 14.º do RITI Artigo 14.º do RITI
M99 Não sujeito; não tributado (ou similar)

Return Values

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

Success
<proforma>
  <id>541090</id>
  <status>draft</status>
  <archived>false</archived>
  <type>Proforma</type>
  <sequence_number>draft</sequence_number>
  <date>07/05/2015</date>
  <due_date>08/05/2015</due_date>
  <reference></reference>
  <observations></observations>
  <retention></retention>
  <permalink>http://www.app.invoicexpress.com/documents/54109072cfff8e9c8f551b0b3be5d90ab78faa6af28d75</permalink>
  <client>
    <id>233429</id>
    <name>Ricardo Pereira</name>
    <code>100</code>
  </client>
  <currency>Euro</currency>
  <items type="array">
    <item>
      <name>Product 1</name>
      <description>Cleaning product</description>
      <unit_price>10.0</unit_price>
      <unit></unit>
      <quantity>1.0</quantity>
      <tax>
        <id>31321</id>
        <name>IVA23</name>
        <value>23.0</value>
      </tax>
      <discount>0.0</discount>
      <subtotal>10.0</subtotal>
      <tax_amount>2.3</tax_amount>
      <discount_amount>0.0</discount_amount>
      <total>12.3</total>
    </item>
    <item>
      <name>Product 2</name>
      <description>Beauty product</description>
      <unit_price>5.0</unit_price>
      <unit></unit>
      <quantity>1.0</quantity>
      <tax>
        <id>31321</id>
        <name>IVA23</name>
        <value>23.0</value>
      </tax>
      <discount>0.0</discount>
      <subtotal>5.0</subtotal>
      <tax_amount>1.15</tax_amount>
      <discount_amount>0.0</discount_amount>
      <total>6.15</total>
    </item>
  </items>
  <sum>15.0</sum>
  <discount>0.0</discount>
  <before_taxes>15.0</before_taxes>
  <taxes>3.45</taxes>
  <total>18.45</total>
</proforma>
Error
Code Description
HTTP: 401 Access denied The API Key parameter is missing or is incorrectly entered.
HTTP: 404 Not Found Account not found
HTTP: 422 Unprocessable Entity Some parameters were incorrect. See below for possible errors.
Possible Errors for HTTP: 422
<errors>
 <error>Your current plan does not allow you to do this</error>
</errors>
<errors>
 <error>Items element should be of type array</error>
</errors>
<errors>
  <error>Country Germani was not found</error>
</errors>
<errors>
  <error>Option to generate MB reference is set, but EasyPay for
   this account is not activated</error>
</errors>
<errors>
 <error>Retention must be a number between 0 and 99.99</error>
 <error>Proforma items is invalid</error>
 <error>Client 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>