Introduction
The endeve API allows developers to connect our invoice management system with third-party applications. If you want to manage your contacts or invoices in your own application, the API can do it for you.
The endeve API is implemented as plain XML over HTTPS using the four REST verbs (GET, POST, PUT and DELETE). Every resource, like invoices or contacts, has its own URL and is manipulated in isolations. In other words, we’ve tried to make the API follow the REST principles making it simple to use.
You can explore any GET method of the API through any browser. For example, if you want to list your sales, just write /sales.xml in your browser.
AUTHENTICATION
You can explore any GET method of the API through any browser. For example, if you want to list your sales, just write /sales.xml in your browser.
You can find your API token in your endeve account, clicking on the “Settings” link on the upper-right side, and then clicking on the “API” on the left, the last element of the navigation menu, under “Personal data”. You’ll find the token in the API token field.
Keep it secret. The API token is your secret password for access to your account. If you think someone has accessed your token, you can always generate a new one just by clicking on Generate a new token.
API READING
We recommend using curl for testing out the various features that the REST API offers.
The REST API has two modes of actions for reading – show and list. Show returns a single record and list returns a collection. You can easily explore REST API reading through a browser.
Examples
REQUEST
curl -u yourAPItoken:bazinga https://www.endeve.com/contacts.xml
This command issues an HTTP GET request to /contacts.xml. It will return HTTP status code 200, and a XML document listing the contacts in your account (by default, this request returns the first ten contacts arranged by name in alphabetical order – you can see more details in the contacts section of the API). If nothing is found, an HTTP 404 “not found” response will be returned.
REQUEST
curl -u yourAPItoken:bazinga https://www.endeve.com/contacts/1.xml
If a contact with ID 1 exists on your account, an XML response is generated along with the status code “200”. The XML response contains the contact data. If nothing is found, the response HTTP 404 “not found” is returned.
API WRITING
When you’re creating and updating REST resources, you’ll be sending XML to endeve. Remember to add the header “Content-type: application/xml”, so that endeve knows that it’s not regular HTML form-encoded data coming in. Then just include the XML of the resource in the body of your request, and you’re done.
If you’re creating a resource you have to use the POST method. A succesful creation responds with the status code “201”. The URL of the new resource is located in the Location header (letting you know where to update your new resource in the future). Also included is the complete XML for the resource in the response. This is handy, as you can usually create a new resource with less than all its regular attributes.
Updating resources is done through the PUT command and against the URL of the resource you want to update. The response to a successful update is “200”.
Examples
REQUEST
curl -u yourAPItoken:bazinga -H “Content-Type: application/xml” -d “<contact><first_name>My customer, S.L.</first_name></contact>” -X POST https://www.endeve.com/contacts.xml
This request creates a new contact with the name My customer, S.L.
REQUEST
curl -u yourAPItoken:bazinga -H “Content-Type: application/xml” -d “<contact><address>C/Profesor Agustín Millares Carló, nº 9</address></contact>” -X PUT https://www.endeve.com/contacts/1.xml
This request updates address of the contact with ID 1.
Any error causes a non 200 or 201 status. An array with all errors is included in the response.
DELETING THROUGH THE API
You can delete resources using the DELETE command. A successful request returns a 200 status.
Example
REQUEST
curl -u yourAPItoken:bazinga -X DELETE https://www.endeve.com/contacts/1.xml
This request deletes the contact with ID 1.
