Rexpense API - Advancements

Advancements

This section describes the API of the advancement resource.

Parameters

id:	integer
description:	string
amount:	float
date:	string
tags:	array
payer:	JSON object
receiver:	JSON object
responsible_user:	JSON object
currency:	string based on currencies code
_links:	array of object array of links of the advancement

Example of Advancement

    {
      "id": 1,
      "description": "Advancement example 1",
      "amount": 609.80,
      "date": "2014-06-01T14:17:56Z",
      "tags": [],
      "payer": {
        "id": 1,
        "name": "Company Inc.",
        "type": "Organization",
        "logo": [
          {
            "style": "original",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/original/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "medium",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/medium/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "thumb",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/thumb/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          }
          {
            "style": "tiny",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/tiny/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          }
        ]
      },
      "receiver": {
        "id": 1,
        "name": "John",
        "type": "User",
        "avatar": [
          {
            "style": "original",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/original/avatar.png",
            "width": 716,
            "height": 655,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "medium",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/medium/avatar.png",
            "width": 300,
            "height": 300,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "thumb",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/thumb/avatar.png",
            "width": 100,
            "height": 100,
            "expiration": "2014-06-27T20:31:43Z"
          }
          {
            "style": "tiny",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/tiny/avatar.png",
            "width": 48,
            "height": 48,
            "expiration": "2014-06-27T20:31:43Z"
          }
        ]
      },
      "responsible_user": {
        "id": 1,
        "name": "John",
        "type": "User",
        "avatar": [
          {
            "style": "original",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/original/avatar.png",
            "width": 716,
            "height": 655,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "medium",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/medium/avatar.png",
            "width": 300,
            "height": 300,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "thumb",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/thumb/avatar.png",
            "width": 100,
            "height": 100,
            "expiration": "2014-06-27T20:31:43Z"
          }
          {
            "style": "tiny",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/tiny/avatar.png",
            "width": 48,
            "height": 48,
            "expiration": "2014-06-27T20:31:43Z"
          }
        ]
      },
      "currency": "BRL",
      "created_at": "2014-06-03T14:17:56Z",
      "updated_at": "2014-06-03T14:17:56Z",
      "_links": [
        {
          "rel": "self",
          "method": "GET",
          "href": "https://app.rexpense.com/api/v1/advancements/1"
        },
        {
          "rel": "update",
          "method": "PUT",
          "href": "https://app.rexpense.com/api/v1/advancements/1"
        },
        {
          "rel": "partial_update",
          "method": "PATCH",
          "href": "https://app.rexpense.com/api/v1/advancements/1"
        },
        {
          "rel": "destroy",
          "method": "DELETE",
          "href": "https://app.rexpense.com/api/v1/advancements/1"
        }
      ]
    }

Retrieve all advancements that the authenticated user can view or manage. It will return a JSON containing the name of the resource with an array of the objects requested and informations like the total of objects, current page and total pages. The fields of the advancements can be found in the Advancement section.

Parameters

page:	integer
per_page:	integer limit to 100

Definition

GET https://app.rexpense.com/api/v1/advancements

Example Request

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "advancements": [{ "id": 1, ... }]
    }

Filtering a list of advancements

You can filter the list of retrieved advancements.

Parameters

All parameters must be nested in the q parameter.

amount_gteq:	float
amount_lteq:	float
receiver_id_eq:	integer
payer_id_eq:	integer
created_at_gteq:	string
created_at_lteq:	string
updated_at_gteq:	string
updated_at_lteq:	string
search_tags:	string
has_tag:	string Available values: '1', '0', ''

Definition

GET https://app.rexpense.com/api/v1/advancements

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"amount_gteq":123.63}}'

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"amount_gteq":3000.00, "amount_lteq": 4000.00}}'

Response Example

    {
      "count": 20,
      "current_page": 1,
      "total_pages": 2,
      "advancements": [{ "id": 1, "amount": 3500.00... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"receiver_id_eq": 1}}'

Response Example

    {
      "count": 0,
      "current_page": 1,
      "total_pages": 1,
      "advancements": [{ "id": 1, "receiver": {"id": 1, "name": "John Smith"} ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"payer_id_eq": 1}}'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "advancements": [{ "id": 1, "payer": {"id": 1, "name": "Organization example 1"} ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"created_at_gteq": "12-24-2013", "created_at_lteq": "12-25-2013"}}'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": ,
      "advancements": [{ "id": 1, "created_at": "2013-12-24T23:59Z" ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"updated_at_gteq": "12-24-2013", "updated_at_lteq": "12-25-2013"}}'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "advancements": [{ "id": 1, "updated_at": "2013-12-24T23:59Z" ... }]
    }

Show an advancement

This request shows the advancement complete information.

Parameters

id:

integer required

Definition

GET https://app.rexpense.com/api/v1/advancements/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/advancements/1 \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json'

Response Example Success

HTTP 200 OK

    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 404 Record Not Found

    {
      "errors": {
        "message": "Record Not Found"
      }
    }

Create an advancements

This request creates a new advancement.

Important:

The payer must have a relation with the receiver to create a new advancement.

Parameters

description:	string
payer:	payer object attributes required id: integer type: string
receiver:	receiver object attributes required id: integer type: string
amount:	float required
tags:	array
date:	string required iso8601 format
currency:	string based on currencies code

Expired organization

If the organization is expired, it will return an 402 error.

Definition

POST https://app.rexpense.com/api/v1/advancements

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/advancements \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -d '{"amount": 1000.00, "date": "2013-12-24", "payer": {"id": 1, "type": "Organization"}}'

Response Example Success

HTTP 201 CREATED

    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity

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

Example Response Failure when organization is expired

HTTP 402 Payment Required

    {
      "errors": {
        "message": "This organization is expired and in read-only mode until this situation have been solved."
      }
    }

Update an advancement

There are two ways to update an advancement: partially or fully. If you'd like to change just one or a few attributes, you have to use the HTTP method PATCH. If you use the HTTP method PUT, you'll have to pass all attributes of the advancement. This behaviour is the same for all resources in the Rexpense API.

Parameters

description:	string
amount:	float required
date:	string required
currency:	string
tags:	array
payer:	payer object attributes required id: integer type: string
receiver:	receiver object attributes required id: integer type: string

Expired organization

If the organization is expired, it will return an 402 error.

Definition

PUT/PATCH https://app.rexpense.com/api/v1/advancements/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X PATCH https://app.rexpense.com/api/v1/advancements/:id \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -d '{"amount": 1200.00, "date": "2014-12-28"}'

Response Example Success

HTTP 200 OK

    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity

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

Example Response Failure when organization is expired

HTTP 402 Payment Required

    {
      "errors": {
        "message": "This organization is expired and in read-only mode until this situation have been solved."
      }
    }

Destroy an advancement

To destroy an advancement you have to own the advancement (be the receiver) or be an Organization's Administrator or Manager (have any relation with the payer).

Expired organization

If the organization is expired, it will return an 402 error.

Definition

DELETE https://app.rexpense.com/api/v1/advancements/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X DELETE https://app.rexpense.com/api/v1/advancements/:id \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json'

Response Example

HTTP 204 NO CONTENT

Example Response Failure when organization is expired

HTTP 402 Payment Required

    {
      "errors": {
        "message": "This organization is expired and in read-only mode until this situation have been solved."
      }
    }

Advancement's activities

Activities are simple logs from an Advancement's changes or comments activities.

If the activity is an Advancement change, the response will hide the source element from the response.

If the activity is a Comment and the content have emojis, they will be rendered as text code by default (for example, :smile:). However, if you'd like to get the unicode of the emojis instead, you should supply a emoji_in_unicode boolean param.

Parameter

emoji_in_unicode:

boolean

Definition

GET https://app.rexpense.com/api/v1/advancements/:advancement_id/activities

Example request

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/advancements/1/activities \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'

Response Example Success

HTTP 200 OK

    {
      "changes": "John create the advancement",
      "occurred_at": "2014-06-01T14:17:56Z",
      "user": {
        "id": 1,
        ...
      }
    }