Sales
The sales have one of the following states: outstanding or paid. A sale is outstanding when the total amount of the payments is inferior to the sale total. On the other hand, a sale is paid when the total amount of the payments is equal or superior to the sale total.
The corresponding values to each state are:
Outstanding 1
Paid 2
SHOW
GET /sales/#{id}.xml
Returns an sale.
RESPONSE
<sale>
<account-id type=“integer”>4127</account-id>
<contact-id type=“integer”>1495</contact-id>
<created-at type=“datetime”>2010-03-18T11:57:30Z</created-at>
<currency>EUR</currency>
<due-date type=“datetime”>2010-04-18T00:00:00Z</due-date>
<id type=“integer”>50761</id>
<issued-at type=“datetime”>2010-03-18T00:00:00Z</issued-at>
<late-fees-rate type=“decimal”>10.0</late-fees>
<notes>Lorem ipsum dolor sit amet</notes>
<number>0056</number>
<paid type=“decimal”>0.0</paid>
<payment-method>Transfer IBAN 0000-0000-00-000000000</payment-method>
<status>1</status>
<total type=“decimal”>127.5</total>
<updated-at type=“datetime”>2010-03-18T11:57:30Z</updated-at>
<items type=“array”>
<item>
<description>Support to endeve.com/description>
<discount-rate type=“decimal”>0.0</discount-rate>
<price type=“decimal”>1150.0</price>
<quantity type=“decimal”>1.0</quantity>
<tax1-name nil=“true”/>
<tax1-rate type=“decimal” nil=“true”/>
<tax2-name>IVA</tax2-name>
<tax2-rate type=“decimal”>-15.0</tax2-rate>
<total type=“decimal”>977.5</total>
</item>
…
<item>
…
</item>
</items>
<payments type=“array”>
<payment>
<amount type=“decimal”>977.5</amount>
<created-at type=“datetime”>2010-03-27T15:37:40Z</created-at>
<date type=“datetime”>2010-03-27T00:00:00Z</date>
<id type=“integer”>33573</id>
<payment-method>Transferencia</payment-method>
<updated-at type=“datetime”>2010-03-27T15:37:40Z</updated-at>
</payment>
…
<payment>
…
</payment>
</payments>
<tags type=“array”>
<tag>
<description>Tag 1</description>
</tag>
…
<tag>
…
</tag>
</tags>
</sale>
LIST
GET /sales.xml
Returns a collection of outstading sales order by issue date descending. In the main node, you’ll find in the attribute count the total number of sales, in the attribute total the total amount of the sales in the collection and in the attribute outstanding the outstanding amount of the sales in the collection.
RESPONSE
<sales>
<sale>
…
</sale>
…
<sale>
…
</sale>
</sales>
The response is paginated and by default just the first 10 sales are returned. If you want to get next 10 sales you could do it using the page parameter. This parameter indicates the page you want to get. By default, is set to 1.
To increase the number of results returned on a page use the per_page parameter. By default, is set to 10. At most you can get 50 sales per page.
You can filter the sales by different criterias. We strongly recomend you to familiarize with filtering sales, log into your account and make some searchs on the sales list. The API implements the same functionality.
By default, the API returns the outstanding sales that have been issued from the last year until today. You can change date range with the filter[from] and filter[to] parameters. You can search by the customer name using the filter[contact_name] parameter. Also, you can list sales by status using filter[status] parameter. With value 1, the API lists outstanding sales, with value 2 lists paid sales and with value 0 lists both.
If not specified, the API lists the sales issued in the currency of your country. You can get the sales issued in other currencies using the filter[currency] parameter. You have to specify the currency ISO code.
If your sales are tagged, you can search by these tags, too, using the filter[tags] parameter. You have to specify the tags separating them by commas.
Examples
/sales.xml?per_page=25&page=2&filter[from]=27/03/2010
This request returns the first 25 outstanding sales issued in euros from 27 March 2010 until today arranged by issue date in descending order. If we want to list both, paid and outstanding sales:
/sales.xml?per_page=25&filter[from]=27/03/2010&filter[status]=0
CREATE
POST /sales.xml
Creates a new sale.
The XML for the new user is returned on a successful request. number and contact-id are mandatory attributes and sale has to have at least one item. For the item, description, price and quantity are mandatory attributes.
If you specify a value for account-id, paid, status or total attributes, it will be ignored. These are read-only attributes.
If you don’t specify an issue date (issued-at), the issue date will be set to today and if you don’t specify a currency, the currency will be set to the currency of your country.
REQUEST
<sale>
<contact-id type=“integer”>1495</contact-id>
<issued-at type=“datetime”>2010-03-27</issued-at>
<number>0056</number>
<items type=“array”>
<item>
<description>Support to endeve.com/description>
<price type=“decimal”>1150.0</price>
<quantity type=“decimal”>1.0</quantity>
</item>
</items>
</sale>
RESPONSE
Status: 201
Location: https://www.endeve.com/sales/#{sale-id}.xml
Optionally, you can include payments and tags in a POST or PUT request. The corresponding objects will be created into the sale.
REQUEST
<sale>
<contact-id type=“integer”>1495</contact-id>
<issued-at type=“datetime”>2010-03-27</issued-at>
<number>0056</number>
<items type=“array”>
<item>
<description>Support to endeve.com/description>
<price type=“decimal”>1150.0</price>
<quantity type=“decimal”>1.0</quantity>
</item>
</items>
<payments type=“array”>
<payment>
<amount type=“decimal”>500.0</amount>
<date type=“datetime”>2010-03-27</date>
<payment-method>Transferencia</payment-method>
</payment>
</payments>
<tags type=“array”>
<tag>
<description>Tag 1</description>
</tag>
<tag>
<description>Tag 2</description>
</tag>
</tags>
</sale>
RESPONSE
Status: 201
Location: https://www.endeve.com/sales/#{sale-id}.xml
This request createas a new sale with one item and one payment, and tagged it with tags “Tag 1” and “Tag 2”.
UPDATE
PUT /sales/#{id}.xml
Updates an existing sale with new details from the submitted XML.
REQUEST
<sale>
<id>50761</id>
<number>0058</number>
</sale>
RESPONSE
Status: 200
Location: https://www.endeve.com/sales/12518310.xml
DELETE
DELETE /sales/#{id}.xml
Destroys the contact at the referenced URL.
RESPONSE
Status: 200
DELIVER
POST /sales/#{id}/deliver.xml
Deliver the sale to his customer.
RESPONSE
Status: 200
