API v3

For the exhaustive list of changes against the API v2 please refer to the Changelog.
API v2 is now deprecated and will be terminated on 31st March 2025.

Request formalities

• All requests must be made via HTTPS.
• All endpoint URLs begin with https://app.fakturoid.cz/api/v3.

Most endpoints require Fakturoid account name as part of the request URL as a slug parameter.

https://app.fakturoid.cz/api/v3/accounts/{slug}/invoices.json

For example if the account name is applecorp, the URL will look like this:

https://app.fakturoid.cz/api/v3/accounts/applecorp/invoices.json

List of all accounts for the current user can be obtained via current user endpoint.

Identification

All requests must have the User-Agent header with the information about the name of your application and a technical contact email so we can contact you in case something goes rogue with your API integration.

User-Agent: YourAppName (administrative@contact.com)

Requests without this header will receive 400 Bad Request error.

JSON

Unless stated otherwise, data (payload) is sent inside the request/response body as an UTF-8 encoded JSON string. Requests that send JSON payload need to have a header Content-Type: application/json.

Requests requesting a different type of response will receive 415 Unsupported Media Type error.

Authorization

Fakturoid supports OAuth 2 protocol for authorization.

Pagination

• Pagination is used on all endpoints that return a collection of records.
• There are 40 records per page.
• Next page can be requested by using the page query parameter.

Error handling

Aside form 2xx success HTTP status codes, the API may also return 4xx client and 5xx server error responses. In case of an error response body always contains a JSON with the description of the error.

Error response body can have two formats. The first one is always used for 422 Unprocessable Entity responses for invalid data and occasionally for other errors as well:

{
  "errors": {
    "name": ["can't be blank"]
  }
}

It contains errors key with a map of fields an their errors. The second format is used for all other errors and always contains error key with a string code of the error and error_description with a human readable description of the error:

{
  "error": "invalid_request",
  "error_description": "Required header \"User-Agent\" is missing"
}

Read-only mode

In case of maintenance, Fakturoid API will respond with status code 503 Temporarily Unavailable. Certain search endpoints may return the same status code when they are busy.

Defensive implementation of the API

Your application should always handle errors returned by the API. In cases of a maintenance or a 5xx server error, your application should retry the request later as Fakturoid does not store the requests for the later processing.

In case of 4xx client error, your application should display the error message to the user or your integration should be updated in a way to fix the error.

Rate-limiting

In case your IP address exceeds 200 requests per minute, the server will respond with the status code 429 Too Many Requests. Please wait a few seconds and retry the request.

Blocked account

If the Fakturoid account is blocked due to an overdue invoice from Fakturoid, the server will respond with status code 402 Payment Required and the response body will contain the list of unpaid invoices.