API documentation

FACTURAgem features a REST API available both as JSON and XML. All the communication with the API must be done via HTTPs. Please make sure your API client is ready for SSL.

A request to the API consists of a HTTP call to our endpoint with optional parameters. Since this is a REST API, it's important to use the appropriate HTTP verb in order to get your results. For example:

• GET https://facturagem.com/api/v1/accounts/1-kovacek-nienow.json, would return the information about this account
• PUT https://facturagem.com/api/v1/accounts/1-kovacek-nienow.json, would update the information of this account with the supplied data

Our API support the verbs POST, GET, PUT, DESTROY

If you want to use the JSON API use ".json" at the end of the URL. If you want to use XML, end your URLs with ".xml"

You can test our full API directly from the API playground console.

Important:if you are using the heroku addon, please refer to heroku specific authentication

Mosf of the operations require authentication. The first step for authenticating a user is creating a session via POST

POST https://facturagem.com/api/v1/session.json (you must provide the parameters 'login' and 'password' for the given user.)

On success, the response of this operation will return the user's information. One of the returned fields is the 'api_key'. This parameter uniquely identifies this user for the duration of the session. You must send it on every request for operations requiring authentication. A fail to do so will cause a Unauthorized (401) status code.

If you try to login and an API key was already generated for the user, the same API key will be returned. If you want to invalidate an API key, you must call the session endpoint issuing a DESTROY request. Please note if a user was logged in via API in multiple devices/applications a call to DESTROY will invalidate the sessions in all of them.

Also note, only users with a password will be able to authenticate via API. If the user enters the site via twitter or facebook and never set a password for accessing, it's necessary to do it before trying to access via API.

FACTURAgem API tries to be as self-discoverable as possible. All the responses will provide links to the returned resource in the array 'links'

For example, when you log in, the response includes these two fields:

• "rel": "self", "uri": "https://facturagem.com/api/v1/session.json". This will link to the returned resource
• "rel": "account", "uri": "https://facturagem.com/api/v1/accounts.json". This will link to the related account

Knowing that the operations follow HTTP verbs standards and having all the linked resources returned on each response, makes it very easy to discover the full API without having to go back to the documentation all the time.

Responses use HTTP status codes to indicate success or failure. This API can respond with the following statuses: 'OK 200, Unauthorized 401, Not Acceptable 406, Unprocessable Entity 422, Not found 404'

In the cases where it doesn't make sense to provide a body, nothing will be sent back. For example, when successfully deleting a resource, finishing a session, or updating a given resource, only the status code will be provided, with no further information.

In the case of GET and POST requests, the requested or newly created resources will be returned.

Validation errors will have a Unprocessable Entity 422 status code. Additionally, the target resource will be returned with an additional field named "errors" containing a description of the problems found.

By default, all the input parameters provided will be checked for correctness. If an unexpected param is found, the system will return a 422 error with a list of the allowed params for this particular operation.

You can use this little trick to figure out which params you can use for any given operation.If you issue any request with a random parameter, you will trigger the params error and get a list of the legal parameters.

Working with params validation can be tedious in some cases, and you can choose to disable them. To override params check, just pass the special param "strict" set to "false" or "0". Note when strict mode is deactivated, you can get Internal Error 500 status responses when trying to create or update some resources if extra params are provided.

Some operations will return a collection of resources. In this case, a list of resource summaries with links to the full information of each resource will be provided.

Client and Invoice collections will be paginated. You can paginate through the results by issuing several times the same GET request and increasing the "page" parameter.

You will know when you reach the end of the results because the collection will be empty.

Accounts cannot be created or destroyed from the API, but can be requested, and updated. All the operations require a valid api_key.

Valid Operations are:

• GET https://facturagem.com/api/v1/accounts/[:id].json gets an account given the id. It must belong to the current user
• GET https://facturagem.com/api/v1/accounts.json convenience methods. It returns the account of the current user
• PUT https://facturagem.com/api/v1/accounts/[:id].json updates the user's account with the provided data

Clients can be created, listed, requested, updated and destroyed from the API. Client operations alwats are below the scope of a given account, and the account_id must be provided as a parameter. All the operations require a valid api_key

Valid Operations are:

• GET https://facturagem.com/api/v1/accounts/[:account_id]/clients.json gets the list of clients for the provided account
• POST https://facturagem.com/api/v1/accounts/[:account_id]/clients.json creates a new client for the provided account
• GET https://facturagem.com/api/v1/accounts/[:account_id]/clients/[:id].json returns the individual client
• PUT https://facturagem.com/api/v1/accounts/[:account_id]/clients/[:id].json updates the individual client
• DESTROY https://facturagem.com/api/v1/accounts/[:account_id]/clients/[:id].json deletes this individual client

Invoices can be created, listed, requested, updated, destroyed and marked as paid from the API. Invoices are always under the scope of an account, so an account_id must be passed for every operation. Some invoice operations can be additionally scoped under a client, and in that case both the account_id and client_id must be provided. All the operations require a valid api_key

Valid Operations are:

• GET https://facturagem.com/api/v1/accounts/[:account_id]/invoices.json gets the list of invoices for the provided account
• GET https://facturagem.com/api/v1/accounts/[:account_id]/clients/[:client_id]/invoices.json gets the list of invoices for the provided account and client
• GET https://facturagem.com/api/v1/accounts/[:account_id]/invoices/new.json returns an empty invoice object scoped for the provided account and prefilled with this account data. Optionally, if a client_id is passed, it will also prefill the client section of the invoice. This is a convenience operation when you want to create an invoice, so you can get the object with most of the fields informed. If you want to create a copy of an invoice, just provide an invoice_id parameter and an empty object with all the params of the original invoice —except the invoice number and the issue date— will be returned.
• POST https://facturagem.com/api/v1/accounts/[:account_id]/invoices.json creates a new invoice for the provided account
• GET https://facturagem.com/api/v1/accounts/[:account_id]/invoices/[:id].json returns the individual invoice
• PUT https://facturagem.com/api/v1/accounts/[:account_id]/invoices/[:id].json updates the individual invoice
• DESTROY https://facturagem.com/api/v1/accounts/[:account_id]/invoices/[:id].json deletes this individual invoice
• POST https://facturagem.com/api/v1/accounts/[:account_id]/invoices/[:id]/payments.json registers a partial payment for the given invoice

If you need to provide a country code, you can look them up issuing a GET request to: https://facturagem.com/api/v1/countries.json

Since this operation doesn't need to sign in, it can be handy for testing purposes of your libraries.