clients.create-invoice
This method allows you to create a new invoice for a specific client.
When creating the invoice:
- 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 invoice on the request body:
Example xml to be submitted with the 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>
<sequence_id>13</sequence_id>
<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>
<mb_reference>1</mb_reference>
</invoice>
Notice there is no client node on the previous xml
Parameters
Parameters are the data you will pass with the call.
api_key
Your secret identifier. Instructions here on how to obtain the API KEY
Rules: Required
client-id
Desired client to assign to the invoice
Rules: Required
date
Invoice 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
Invoice date 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.
sequence_id
Id of the sequence you want to use with this invoice, if missing the default sequence will be used.
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
mb_reference
Generates a Multibanco Reference after you finalize your invoice. This option is only available for Portuguese Accounts.
Rules: Optional. You must have Compra Facil enabled on your account first.
Return Values
Success
HTTP: 201 CREATED
<?xml version="1.0" encoding="UTF-8"?> <invoice> <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>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> <preferred_contact> <name>Bruce Norris</name> <email>foo@bar.com</email> <phone>2233442233</phone> </preferred_contact> <observations>Computer Processed</observations> <send_options>1</send_options> </client> <currency>Euro</currency> <items type="array"> <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> </invoice>
Errors
HTTP: 401 Access denied
The API Key parameter is missing or incorrect.
HTTP: 422 Unprocessable Entity
Some parameters were incorrect:
<?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>Invoice 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> <error>Unit is not included in the list of accepted units</error> </errors> <?xml version="1.0" encoding="UTF-8"?> <errors> <error>Items element should be of type array</error> </errors> <?xml version="1.0" encoding="UTF-8"?> <errors> <error>Country Germani was not found</error> </errors> <?xml version="1.0" encoding="UTF-8"?> <errors> <error>Option to generate MB reference is set, but Compra Facil for this account is not activated</error> </errors>