Rexpense API - Expenses

Expenses

This section describes the API of the expense resource.

Parameters

id:	integer
kind:	string
description:	string
distance:	float
distance_kind:	string
destination:	string
destination_latitude:	float
destination_longitude:	float
origin:	string
origin_latitude:	float
origin_longitude:	float
travel_time:	string String format "HH:MM"
amount:	float
approved_amount:	float
status:	string
occurred_at:	string
payer:	JSON object
receiver:	JSON object
attachments:	array of objects array of an attachment representation
tags:	array
currency:	string based on currencies code
approved_amount_currency:	string based on currencies code
latitude:	float
longitude:	float
location:	string
attachments_count:	integer
comments_count:	integer
activities_count:	integer
liquidation_through:	string (advancement, reimbursement or corporative_card)
_links:	array of object array of links of the expense

The following parameters will only available when the expense kind is distance.

distance:	float
distance_kind:	string
destination:	string
destination_latitude:	float
destination_longitude:	float
origin:	string
origin_latitude:	float
origin_longitude:	float
travel_time:	string String format "HH:MM"

Example of Expense

    {
      "id": 1,
      "description": "Expense example 1",
      "amount": 120.00,
      "approved_amount": 100.00,
      "approved_amount_currency": "USD",
      "kind": "distance", // only when kind is distance
      "distance": 3.4, // only when kind is distance
      "distance_kind": "km", // only when kind is distance
      "destination": "R. Lourival França, 31-37 - Vista Alegre, São Gonçalo - RJ", // only when kind is distance
      "destination_latitude": -35.2060689 // only when kind is distance,
      "destination_longitude": -5.8718724 // only when kind is distance,
      "origin": "R. Dona Antônia Couto, 1408-1628 - Bom Retiro, São Gonçalo - RJ, 24726-135", // only when kind is distance
      "origin_latitude": -5.8928447 // only when kind is distance,
      "origin_longitude": -35.205913 // only when kind is distance,
      "travel_time": 60, // only when kind is distance
      "status": "awaiting_analysis",
      "occurred_at": "2014-06-01T14:17:56Z",
      "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"
          }
        ]
      },
      "attachments": [
        {
          "id": 1,
          "description": "Hotel in China",
          "uploaded_at" : "2014-06-23T14:31:14Z",
          "content_type": "image/png",
          "file_name": "expense.png",
          "url": "https://rexpense-direct-uploads.s3.amazonaws.com/uploads/1/original/expense.png",
          "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Rexpense",
            "mention_name": "JohnRexpense",
            "emails": [
              {
                "email": "john@rexpense.com",
                "main": true
              }
            ]
          }
        }
      ],
      "tags": "lunch, conference, 2014, new clients",
      "currency": "BRL",
      "latitude": -22.913444,
      "longitude": -47.051059,
      "location": "R. Cap. Pedro de Alcântara, 212 - Jardim Primavera, SP, 13026-390, República Federativa do Brasil",
      "attachments_count": 1,
      "comments_count": 1,
      "activities_count": 1,
      "liquidation_through": "advancement",
      "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/expenses/1"
        },
        {
          "rel": "update",
          "method": "PUT",
          "href": "https://app.rexpense.com/api/v1/expenses/1"
        },
        {
          "rel": "partial_update",
          "method": "PATCH",
          "href": "https://app.rexpense.com/api/v1/expenses/1"
        },
        {
          "rel": "destroy",
          "method": "DELETE",
          "href": "https://app.rexpense.com/api/v1/expenses/1"
        }
      ]
    }

Retrieve all expenses 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 expenses can be found in the Expense section.

Parameters

page:	integer
per_page:	integer limit to 100

Definition

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

Example Request

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

Response Example

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

Filtering a list of expenses

You can filter the list of retrieved expenses.

Parameters

All parameters must be nested a 'q' parameter.

status_in:	string
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:	array of string accepted values: '1', '0', ''
liquidation_through_in:	array of strings accepted values: advancement, reimbusement, corporative_card
corporative_card_id_in:	array of integers

Definition

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

Request example

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

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "expenses": [{ "id": 1, "status": "awaiting_analysis"... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/expenses \
      -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,
      "expenses": [{ "id": 1, "amount": 3500.00... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/expenses \
      -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,
      "expenses": [{ "id": 1, "receiver": {"id": 1, "name": "John Smith"} ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/expenses \
      -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,
      "expenses": [{ "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/expenses \
      -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": ,
      "expenses": [{ "id": 1, "receiver": {"id": 1, "created_at": "2013-12-24T23:59Z"} ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/expenses \
      -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,
      "expenses": [{ "id": 1, "receiver": {"id": 1, "updated_at": "2013-12-24T23:59Z"} ... }]
    }

Show an expense

This request shows the expense complete information.

If the Expense is originated from a Pre-Expense, it will contain the field pre_expense_id. To learn more about PreExpense visit its section.

Parameters

id:

integer required

Definition

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

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/expenses/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 expense

This request creates a new expense.

Important:

The authenticated user must belong to an organization to create a new expense.
It's not possible to set attachments_count, comments_count and activities_count fields.

Parameters

description:	string
payer:	payer object attributes required id: integer type: string
amount:	float required
occurred_at:	string iso8601 format required
tags:	string
latitude:	float
longitude:	float
location:	string
liquidation_through:	string required accepted values: advancement, reimbursement or corporative_card
corporative_card_id:	integer optional required only when liquidation_through is corporative_card

To create an expense with distance kind, you have to send the kind param with "distance" value. In travel values is required distance and distance_kind where can be "km" or "mi". The travel_time field receive a string in format "HH:MM" and show minutes value, example: "01:01" returns 61 minutes. Distance expenses d'not need amount, but have send distance informations:

kind:	string required
distance:	string required
distance_kind:	string required
destination:	string
destination_latitude:	float
destination_longitude:	float
origin:	string
origin_latitude:	float
origin_longitude:	float
travel_time:	string

To create an expense with attachments, you have to send the attachments_attributes parameters. This parameters is an array containing one or multiple JSON objects with the following information:

file:	string required
description:	string

The file parameter must be an URL of the attachment. This URL may be achieve following the steps in Uploads section.

Expired organization

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

Definition

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

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/expenses \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -d '{"amount": 1000.00, "occurred_at": "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 expense

There are two ways to update an expense: 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 expense. This behaviour is the same for all resources in the Rexpense API.

Parameters

description:	string
amount:	float required
approved_amount:	float
occurred_at:	string required
tags:	string
latitude:	float
longitude:	float
location:	string
liquidation_through:	string accepted values: advancement, reimbursement or corporative_card
corporative_card_id:	string optional (only when liquidation_through is corporative_card)

To create an expense with distance kind, you have to send the kind param with "distance" value. Distance expenses d'not need amount, but have send distance informations:

distance:	string required
distance_kind:	string required
destination:	string required
destination_latitude:	float
destination_longitude:	float
origin:	string required
origin_latitude:	float
origin_longitude:	float
travel_time:	string

To update the expense's attachments, you have to send the attachments_attributes parameters. This parameter is an array containing JSON objects with the following information:

id:	integer
description:	string
file:	string required
_destroy:	boolean

The file parameter must be an URL of the attachment. This URL may be achieve following the steps in Uploads section.

To remove an attachment, you have to pass the _destroy parameter with value true and the id with the id of the attachment to be removed.

Status 'Pending'

When updating a Pending expense, it'll change its status to Awaiting analysis, so an Administrator/Manager/Analyst can check the new informations on the expense.

Expired organization

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

Definition

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

Example Request

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

Response Example Success

HTTP 200 OK

    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity

    {
      "errors": {
        "occurred_at": ["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 expense

To destroy an expense you have to own the expense (be the receiver) and it's status must be Awaiting analysis. Also an Organization's Administrator or Manager can destroy any expense that belongs to the organization.

Expired organization

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

Definition

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

Example Request

$ curl -u $YOUR_API_TOKEN:X -X DELETE https://app.rexpense.com/api/v1/expenses/: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."
      }
    }

Expense's activities

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

If the activity is an Expense 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/expenses/:expense_id/activities

Example request

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

Response Example Success

HTTP 200 OK

    {
      "changes": "John made a new comment: This is my first comment.",
      "occurred_at": "2014-06-01T14:17:56Z",
      "source": {
        "id": 1,
        "type": "Comment"
        ...
      },
      "user": {
        "id": 1,
        ...
      }
    }