API

Application Programming Interface

InvoiceXpress Documentation



Create


schedules.create

Creates a new schedule. 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 one is created. Regarding item taxes, if the tax name is not found, it is ignored and no tax is applied to that item.

If no item exists 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 schedule items, as any missing items from the original schedule are deleted.

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

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

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

Body
<schedule>
  <start_date>30/10/2009</start_date>
  <end_date>30/10/2020</end_date>
  <create_back>Yes</create_back>
  <schedule_type>Monthly</schedule_type>
  <interval>2</interval>
  <send_to_client>Yes</send_to_client>
  <description>One description</description>
  <invoice_template>
    <date>30/10/2009</date>
    <due_date>31/10/2009</due_date>
    <due_days>0</due_days>
    <reference></reference>
    <observations></observations>
    <retention></retention>
    <client>
      <name>Client</name>
      <email>someone@example.com</email>
      <address></address>
      <postal_code></postal_code>
      <fiscal_id></fiscal_id>
    </client>
    <items type="array">
      <item>
        <name>Product x</name>
        <description></description>
        <unit_price>0.0</unit_price>
        <quantity>3.0</quantity>
        <tax>
          <name>IVA20</name>
        </tax>
        <discount>0.0</discount>
      </item>
      <item>
        <name>Product y</name>
        <description></description>
        <unit_price>0.0</unit_price>
        <quantity>3.0</quantity>
        <tax>
          <name>IVA20</name>
        </tax>
        <discount>0.0</discount>
      </item>
    </items>
  </invoice_template>
</schedule>

Parameters

Parameters are the data you will pass with the call.

Property Required Description
api_key Yes Your secret identifier. You can find your API Key under Account >> API in the Account section.
start_date Yes Date your schedule starts
end_date Yes Date your schedule ends
create_back No Creates all the invoices between the schedule start_date and the current date. Options are: Yes – Create the invoices. No – Don’t create the invoices (also the default)
schedule_type Yes Schedule interval unit. Options are: Daily – interval is measured in days. Monthly – interval is measured in months. Yearly – interval is measured in years.
interval Yes The schedule periodicity. Must be a number equal or greater than 0.
send_to_client Yes If this option is set to Yes, in the scheduled dates, the invoice is automatically created, finalized and sent to the client. Otherwise only a draft is created.
description Yes Schedule description.
invoice_template / date Yes Date of the invoice.
invoice_template / due_date Yes Due date of the invoice.
invoice_template / due_days Yes Days between each invoice date and due_date
invoice_template / reference No Reference, usually a purchase order.
invoice_template / observations No Observations, these will be printed with the invoice.
invoice_template / retention No Withholding tax percentage (%). Must be a number between 0 and 99.99
invoice_template / client / name Yes Client name. If the client doesn’t exist a new one will be created. If it exists the remaining client fields will be ignored.
invoice_template / client / email No Client email.
invoice_template / client / address No Client company address.
invoice_template / client / city No Client’s city.
invoice_template / client / postal_code No Client’s postal code for it’s company address.
invoice_template / client / fiscal_id No The client fiscal ID (Número de Contribuinte)
invoice_template / items Yes An array of 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.
invoice_template / item / name Yes Name of the item. Must be unique.
invoice_template / item / description Yes Item’s description
invoice_template / item / unit_price Yes Item’s unit price. Must be a number equal or greater than 0.0.
invoice_template / item / quantity Yes Quantity. Must be a number equal or greater than 0.
item / unit No The item unit of measure
invoice_template / item / discount No The item discount percentage(%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.
invoice_template / item / tax No The tax applied to the item line. If not present no tax is applied to the item
invoice_template / 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: 201 CREATED
<schedule>
   <id>26</id>
   <next_date>30/01/2010</next_date>
   <next_due_date>30/01/2010</next_due_date>
   <reference></reference>
   <observations></observations>
   <retention>4.0</retention>
   <client>
     <name>Client</name>
     <email>someone@example.com</email>
     <address></address>
     <postal_code></postal_code>
     <fiscal_id></fiscal_id>
   </client>
   <currency>Euro</currency>
   <items>
     <item>
       <id>21</id>
       <name>Product x</name>
       <description></description>
       <unit_price>3.0</unit_price>
       <quantity>2.0</quantity>
       <tax>
         <name>IVA20</name>
         <value>20.0</value>
       </tax>
       <discount>4.0</discount>
     </item>
     <item>
       <id>16</id>
       <name>Product y</name>
       <description></description>
       <unit_price>0.0</unit_price>
       <quantity>3.0</quantity>
       <tax>
         <name>IVA20</name>
         <value>20.0</value>
       </tax>
       <discount>0.0</discount>
     </item>
   </items>
   <sum>6.0</sum>
   <discount>0.24</discount>
   <before_taxes>5.76</before_taxes>
   <taxes>1.15</taxes>
   <total>6.68</total>
 </schedule>
Error
Code Description
HTTP: 401 Access denied The API Key parameter is missing or is incorrectly entered.
HTTP: 422 Unprocessable Entity Some parameters were incorrect.

Possible errors for HTTP: 422

<errors>
 <error>Invoice is invalid</error>
 <error>Interval must be greater than 0</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>
</errors>