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"

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.

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

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