Introduction

Welcome to Quipu API.

Quipu is an invoice and taxes software as a service for freelances and companies.

Feel free to use our API and develop amazing things. To use our API you need to sign up in our software here.

You will have 15 days to try it for free. If you need more time just contact our support team and we will extend the days.

You can get more information about our API, libraries and other applications here: https://getquipu.com/en/integrations.

REST API Conventions

The Quipu API is based on … JSON API

All request should include the header Accept: application/vnd.quipu.v1+json.

All POST, PUT and PATCH request must include the header Content-Type: application/vnd.quipu.v1+json, except when specifically indicated otherwise.

Filtering

When fetching collections of resources you can use filter[filter_name]=filter_value query params.

The available filters are detailed in each section.

Example:

GET /invoices?filter[period]=1Q-2015&filter[kind]=income

Sorting

When fetching some collections of resources you can use ?sort=sort_criteria_1,sort_criteria_2,-sorting_criteria_3,..., each sorting criteria separated with a comma.

The - sign at the beggining of a sorting criteria means that the order for this criteria is descendant.

Example:

GET /invoices?sort=-issued_at,total_amount # => order_by issued_at desc, total_amount asc;

Rate limiting

In order to guarantee a fair usage of the platform by all users, we set a maximum of 5 requests every 5 seconds (effectively 900 requests every 15 minutes), for a specific pair of credentials.

We implement the standard RateLimit headers defined in section 3 of this document so the API user can know the limit, how much usage there is left, and when will this usage be reset.

In the event that a request surpasses the allocated limit for that account, a 429 status code will be returned.

Endpoints summary

Contacts

• GET /contacts
• POST /contacts
• GET /contacts/:id
• PATCH /contacts/:id
• DELETE /contacts/:id

Invoices, tickets and paysheets

• GET /book_entries

Invoices

• GET /invoices
• POST /invoices
• GET /invoices/:id
• PATCH /invoices/:id
• DELETE /invoices/:id

Tickets

• GET /tickets
• POST /tickets
• GET /tickets/:id
• PATCH /tickets/:id
• DELETE /tickets/:id

Paysheets

• GET /paysheets
• POST /paysheets
• GET /paysheets/:id
• PATCH /paysheets/:id
• DELETE /paysheets/:id

Numbering series

• GET /numbering_series
• POST /numbering_series
• GET /numbering_series/:id
• PATCH /numbering_series/:id
• DELETE /numbering_series/:id

Analytic categories

• GET /analytic_categories
• POST /analytic_categories
• GET /analytic_categories/:id
• PATCH /analytic_categories/:id
• DELETE /analytic_categories/:id

Accounting categories

• GET /accounting_categories
• GET /accounting_categories/:id

Accounting subcategories

• GET /accounting_subcategories
• POST /accounting_subcategories
• GET /accounting_subcategories/:id
• PATCH /accounting_subcategories/:id
• DELETE /accounting_subcategories/:id

Attachments

• POST /attachments
• GET /attachments/:id
• DELETE /attachments/:id

Authentication

We use OAuth2 to authorize the requests.

Getting an access token

Example request

curl "https://getquipu.com/oauth/token" \
  -H "Authorization: Basic UHROeGZDc0drbGltRXJRcVZUZUFGRFVUVWpkTVZDcmpORklsclJlS..." \
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  -d "scope=ecommerce" \
  -d "grant_type=client_credentials"

Example response

{
  "token_type":    "bearer",
  "created_at":    1456339025,
  "access_token":  "7c74b8e69bdd19a90e1ffaf987ada2ca67b948b0bed7b2cf95ad58f5ecb14294",
  "refresh_token": null,
  "expires_in":    1456346225
}

To get an access token you will need the account’s app_id and app_secret credentials.

As is standard in basic access authentication, the header’s structure corresponds to Authorization Basic credentials, where credentials is the result of:

• Joining app_id and app_secret by a single colon
• Applying Base64 (URL safe mode) to the result

Example:

• if app_id were PtNxfCsGklimErQqVTeAFDUTUjdMVCrjNFIlrReIimSHKMoOaWxAxwHPNevbIwFV
• and app_secret were HRcqlIcHjYUWunjgVmAQiWYjbYFAGSoLhpXkHoGPhjdwQmXmRIxDQOQJOANpfnbD
• then the header would be Authorization Basic UHROeGZDc0drbGltRXJRcVZUZUFGRFVUVWpkTVZDcmpORklsclJlSWltU0hLTW9PYVd4QXh3SFBOZXZiSXdGVjpIUmNxbEljSGpZVVd1bmpnVm1BUWlXWWpiWUZBR1NvTGhwWGtIb0dQaGpkd1FtWG1SSXhEUU9RSk9BTnBmbmJE

Using the token in the requests

Example request

curl "https://getquipu.com/invoices" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Contacts

Endpoints to manage contacts

Listing contacts

Example request

curl "https://getquipu.com/contacts" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "45923",
    "type": "contacts",
    "attributes": {
      "name": "PEPEMOBILE S.L.",
      "tax_id": "ESB85033470",
      "phone": "999999999",
      "email": "pepe@phone.com",
      "address": "Paseo de la Castellana 8, 7-D",
      "town": "Madrid",
      "zip_code": "28046",
      "country_code": "es",
      "total_paid_incomes": "13284.56",
      "total_unpaid_incomes": "0.0",
      "total_incomes": "13284.56",
      "total_paid_expenses": "0.0",
      "total_unpaid_expenses": 0.0,
      "total_expenses": "0.0",
      "client_number": "6",
      "supplier_number": null,
      "is_client": true,
      "is_supplier": false,
      "is_employee": false,
      "is_supplier_of_direct_goods": false,
      "bank_account_number": "ES92 3821 0601 2314 3339 5656",
      "bank_account_swift_bic": "",
      "deletable": false
    }, {
    "id": "45956",
    "type": "contacts",
    "attributes": {
      "name": "Amazon EU S.a.r.l., España",
      "tax_id": "ESW0184081H",
      "phone": "999999999",
      "email": "",
      "address": "Via De Las Dos Castillas, 33, Atica Ed. 2",
      "town": "Pozuelo de Alarcón",
      "zip_code": "28224",
      "country_code": "es",
      "total_paid_incomes": "0.0",
      "total_unpaid_incomes": "0.0",
      "total_incomes": "0.0",
      "total_paid_expenses": "263.15",
      "total_unpaid_expenses": 0.0,
      "total_expenses": "263.15",
      "client_number": null,
      "supplier_number": 931,
      "is_client": false,
      "is_supplier": true,
      "is_employee": false,
      "is_supplier_of_direct_goods": false,
      "bank_account_number": "ES92 3821 0601 2314 3339 5656",
      "bank_account_swift_bic": "",
      "deletable": false
    }
  }, {

    ...

  }],
  meta: {
    pagination_info: {
      "total_pages": 2
      "current_page": 1
      "total_results": 23
    }
  }
}

GET /contacts

Available filters

Filter name	Description	Valid values	Example
q	Search by name	Any	/contacts?filter[q]=amazon
kind	Filter contacts by kind	employee, supplier and client	contacts?filter[kind]=client
tax_id	Filter contacts by their tax id		contacts?filter[tax_id]=43456628J
country	Filter contacts by one or many countries, separated by commas	any country code, in downcase, under the ISO 3166-1 Alpha-2	contacts?filter[country]=es,it
email	Filter contacts by email	Any	contacts?filter[email]=someemail@provider.domain

Sorting

Criteria name	Description	Example
name	Sorts contacts by name	/contacts?sort=name
total_paid_income	Sorts contacts by the amount of money they have paid to us	/contacts?sort=-total_paid_income
total_unpaid_income	Sorts contacts by the amount of money they owe us	/contacts?sort=total_unpaid_income
total_paid_expenses	Sorts contacts by the amount of money we have paid to them	/contacts?sort=total_paid_expenses
total_unpaid_expenses	Sorts contacts by the amount of money we owe them	/contacts?sort=-total_unpaid_expenses

Pagination

20 contacts in every response. Total pages indicated by total_pages in response meta object.

You can request a specific page with a query param: GET /contacts?page[number]=7

Getting a contact

Example request

curl "https://getquipu.com/contacts/45923" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": {
    "id": "45923",
    "type": "contacts",
    "attributes": {
      "name": "PEPEMOBILE S.L.",
      "tax_id": "ESB85033470",
      "phone": "999999999",
      "email": "pepe@phone.com",
      "address": "Paseo de la Castellana 8, 7-D",
      "town": "Madrid",
      "zip_code": "28046",
      "country_code": "es",
      "total_paid_incomes": "13284.56",
      "total_unpaid_incomes": "0.0",
      "total_incomes": "13284.56",
      "total_paid_expenses": "0.0",
      "total_unpaid_expenses": 0.0,
      "total_expenses": "0.0",
      "client_number": "6",
      "supplier_number": null,
      "is_client": true,
      "is_supplier": false,
      "is_employee": false,
      "is_supplier_of_direct_goods": false,
      "bank_account_number": "ES92 3821 0601 2314 3339 5656",
      "bank_account_swift_bic": "",
      "deletable": false
    }
  }
}

GET /contact/:contact_id

Creating a contact

Example request

curl "https://getquipu.com/contacts" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "contacts",
          "attributes": {
            "name": "PEPEMOBILE S.L.",
            "tax_id": "ESB85033470",
            "phone": "999999999",
            "email": "pepe@phone.com",
            "address": "Paseo de la Castellana 8, 7-D",
            "town": "Madrid",
            "zip_code": "28046",
            "country_code": "es",
            "client_number": 6,
            "supplier_number": null,
            "is_supplier_of_direct_goods": false,
            "bank_account_number": "ES92 3821 0601 2314 3339 5656",
            "bank_account_swift_bic": ""
          }
        }
      }'

Example response (status: 204)

{
  "data": {
    "id": "45923",
    "type": "contacts",
    "attributes": {
      "name": "PEPEMOBILE S.L.",
      "tax_id": "ESB85033470",
      "phone": "999999999",
      "email": "pepe@phone.com",
      "address": "Paseo de la Castellana 8, 7-D",
      "town": "Madrid",
      "zip_code": "28046",
      "country_code": "es",
      "total_paid_incomes": "13284.56",
      "total_unpaid_incomes": "0.0",
      "total_incomes": "13284.56",
      "total_paid_expenses": "0.0",
      "total_unpaid_expenses": 0.0,
      "total_expenses": "0.0",
      "client_number": "6",
      "supplier_number": null,
      "is_client": true,
      "is_supplier": false,
      "is_employee": false,
      "is_supplier_of_direct_goods": false,
      "bank_account_number": "ES92 3821 0601 2314 3339 5656",
      "bank_account_swift_bic": "",
      "deletable": false
    }
  }
}

Example response (status 422)

{
  "errors": [
    {
      "detail": "Can not be blank.",
      "source": {
        "pointer": "/data/attributes/name"
      }
    }, {
      "detail": "This Iban is not valid, please contact your bank and provide a new one.",
      "source": {
        "pointer": "/data/attributes/bank_account_number"
      }
    }
  ]
}

POST /contacts

Updating a contact

curl "https://getquipu.com/contacts/746868" \
  -X PATCH
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "contacts",
          "attributes": {
            "name": "Another name",
            "email": "another@name.com",
            "bank_account_number": "ES92 3821 0601 2314 3339 5656",
          }
        }
      }'

Example response (status: 200)

{
  "data": {
    "id": "45923",
    "type": "contacts",
    "attributes": {
      "name": "Another name",
      "tax_id": "ESB85033470",
      "phone": "999999999",
      "email": "another@name.com",
      "address": "Paseo de la Castellana 8, 7-D",
      "town": "Madrid",
      "zip_code": "28046",
      "country_code": "es",
      "total_paid_incomes": "13284.56",
      "total_unpaid_incomes": "0.0",
      "total_incomes": "13284.56",
      "total_paid_expenses": "0.0",
      "total_unpaid_expenses": 0.0,
      "total_expenses": "0.0",
      "client_number": "6",
      "supplier_number": null,
      "is_client": true,
      "is_supplier": false,
      "is_employee": false,
      "is_supplier_of_direct_goods": false,
      "bank_account_number": "ES92 3821 0601 2314 3339 5656",
      "bank_account_swift_bic": "",
      "deletable": false
    }
  }
}

(PATCH|PUT) /contacts/:contact_id

Deleting a contact

curl "https://getquipu.com/contacs/45923" \
  -X DELETE
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

DELETE /contacts/:contact_id

The response status will be 204 - No Content if the operation was successfull or 403 - Forbidden if the contact could not be deleted (or authorization fails). A contact can not be deleted if there are invoices or paysheets associated with it.

Invoices, tickets and paysheets

Only one available action. Get a list with different type of resources

Listing invoices, tickets and paysheets alltoghether

Example request

curl "https://getquipu.com/book_entries" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "2988939",
    "type": "invoices",
    "attributes": {
      "kind": "income",
      "number": "2016-2",
      "issue_date": "2016-02-29",
      "due_dates": [],
      "paid_at": "2016-03-02",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "validation_status": "pending",
      "total_amount": "2472.98",
      "total_amount_without_taxes": "2333.0",
      "vat_amount": "489.93",
      "retention_amount": "349.95"
      "issuing_name": "Paolo Conte",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "QuipuApp S.L.",
      "recipient_tax_id": "B66086042",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "es",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3399147"
        }]
      }
    }
  }, {
    "id": "2937714",
    "type": "invoices",
    "attributes": {
      "kind": "income",
      "number": "2016-1",
      "issue_date": "2016-01-31",
      "due_dates": [],
      "paid_at": "2016-02-03",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "total_amount": "2472.98",
      "total_amount_without_taxes": "2333.0",
      "vat_amount": "489.93",
      "retention_amount": "349.95"
      "issuing_name": "Paolo Conte",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "QuipuApp S.L.",
      "recipient_tax_id": "B66086042",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "es",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data": []
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3319559"
        }]
      }
    }
  }, {
    "id": "2698918",
    "type": "tickets",
    "attributes": {
      "kind": "expenses",
      "number": "8",
      "issue_date": "2015-07-18",
      "due_dates": [],
      "paid_at": "2015-10-04",
      "payment_method": "",
      "payment_status": "paid",
      "validation_status": "verified",
      "total_amount": "5.2",
      "issuing_name": "Bar Paco",
      "issuing_tax_id": null,
      "issuing_address": null,
      "issuing_phone": null,
      "issuing_town": null,
      "issuing_zip_code": null,
      "issuing_country_code": null,
      "recipient_name": "Paolo Conte",
      "recipient_tax_id": "43467890F",
      "recipient_address": "C/ Viladomat 39",
      "recipient_phone": "123456789",
      "recipient_town": "San Cucufate",
      "recipient_zip_code": "09876",
      "recipient_country_code": "es",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "53"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": null
      },
      "analytic_categories": {
        "data": []
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "2957853"
        }]
      }
    }
  }, {

  ...

  },
  "meta": {
    pagination_info: {
      "total_pages": 2
      "current_page": 1
      "total_results": 23
    }
  }
}

GET /book_entries

Available filters

Filter name	Description	Valid values	Example
type	Filters resources by type	invoices, tickets or paysheets	/book_entries?filter[type]=invoices
kind	Filter resources by kind	expenses or income	/book_entries?filter[kind]=expenses
q	Search	Any	/book_entries?filter[q]=android development
period	Filter resources issued in the specified period	year-[month number,Q1,Q2,Q3,Q4] from=DATE&to=DATE (the difference between them must be less than one year)	/book_entries?filter[period]=2015-Q1 => First quarter of 2015 /book_entries?filter[period]=2016-2 => February 2016 /book_entries?filter[period]=2015 => 2015 book_entries?filter[period][from]=2015-04-03&filter[period][to]=2015-07-14
payment_status	Filter resources by payment status	paid, unpaid, due or pending	/book_entries?filter[payment_status]=due
contact_id	Filter by contact	The contact ID	/book_entries?filter[contact_id]=1234
field_query	Filter by contact, concept, number, tag or user name	name of the field and the search term	/book_entries?filter[field_query][field]=label&filter[field_query][term]=tag_name

Sorting

Criteria name	Description	Example
number	Sorts resources by number	/book_entries?sort=-number
issue_date	Sort resources by issue date	/book_entries?sort=-issue_date
counterpart_name	Sorts resources by the counterpart name (issuing_name or recipient_name depending on the kind)	/book_entries?sort=counterpart_name
total_amount	Sort resources by the total amount field	/book_entries?sort=-total_amount
total_amount_without_taxes	Sort resources by the total amount before apply any tax	/book_entries?sort=total_amount_without_taxes

Invoices

Endpoints to manage invoices.

Attributes

Attr. name	Constraints
kind	REQUIRED Accepted values: income or expenses
number	For income invoices we recommend leave it blank, and Quipu will assign it. For income invoices must be unique within a fiscal year. For expense invoices must be unique within a fiscal year for the invoice supplier.
issue_date	REQUIRED Format: YYYY-mm-dd
due_dates	Format: an array of dates with format YYYY-mm-dd
paid_at	Format: YYYY-mm-dd
payment_method	Accepted valued: cash, bank_transfer, bank_card, direct_debit, paypal, check, factoring
payment_status	READ ONLY
total_amount	READ ONLY
total_amount	READ ONLY
total_amount_without_taxes	READ ONLY
vat_amount	READ ONLY
retention_amount	READ ONLY
issuing_name	READ ONLY, *
issuing_tax_id	READ ONLY, *
issuing_address	READ ONLY, *
issuing_phone	READ ONLY, *
issuing_town	READ ONLY, *
issuing_zip_code	READ ONLY, *
issuing_country_code	READ ONLY, *
recipient_name	READ ONLY, *
recipient_tax_id	READ ONLY, *
recipient_address	READ ONLY, *
recipient_phone	READ ONLY, *
recipient_town	READ ONLY, *
recipient_zip_code	READ ONLY, *
recipient_country_code	READ ONLY, *
last_sent_at	Format: a unix timestamp
tags	Format: a list of strings separated by comma
notes	Format: a string
download_pdf_url	Url to download the pdf document for the invoice. Present only in income invoices. Needs the same authorization header.
ephemeral_open_download_pdf_url	Url to download the pdf document for the invoice. Present only in income invoices. Does not need any authorization header, but can only be used for an hour after getting it.

* This fields will be populated and updated each time an invoice is saved from the information of the Quipu account owner and the contact associated with the book entry.

Relationships

Relationship name	Constraints
contact	REQUIRED (except for amending invoices)
accounting_category
accounting_subcategory
numeration	Applicable only to invoices with kind = income
analytic_categories	Can not be a root analytic category
items	Can be sideloaded in GET requests. Must be included in the payload in POST/PATCH/PUT requests
amended_invoice	The invoice amended by the current one.
amending_invoices	Invoices that amend the current one (Read Only)

Listing invoices

Example request

curl "https://getquipu.com/invoices" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "2988939",
    "type": "invoices",
    "attributes": {
      "kind": "income",
      "number": "2016-2",
      "issue_date": "2016-02-29",
      "due_dates": ["2016-03-31"],
      "paid_at": "2016-03-02",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "total_amount": "2472.98",
      "total_amount_without_taxes": "2333.0",
      "vat_amount": "489.93",
      "retention_amount": "349.95"
      "issuing_name": "Paolo Conte",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "QuipuApp S.L.",
      "recipient_tax_id": "B66086042",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "es",
      "tags": "",
      "last_sent_at": 1457364458
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3399147"
        }]
      }
    }
  }, {
    "id": "2937714",
    "type": "invoices",
    "attributes": {
      "kind": "income",
      "number": "2016-1",
      "issue_date": "2016-01-31",
      "due_dates": [],
      "paid_at": "2016-02-03",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "total_amount": "2472.98",
      "total_amount_without_taxes": "2333.0",
      "vat_amount": "489.93",
      "retention_amount": "349.95"
      "issuing_name": "Paolo Conte",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "QuipuApp S.L.",
      "recipient_tax_id": "B66086042",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "es",
      "tags": "vip client, important",
      "last_sent_at": 1457364458
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data": []
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3319559"
        }]
      }
    }
  }, {

  ...

  },
  "meta": {
    pagination_info: {
      "total_pages": 2
      "current_page": 1
      "total_results": 23
    }
  }
}

GET /invoices

Paginated. 20 results per page

Available filters

See Invoices, tickets and paysheets => Available filters

Sorting

See Invoices, tickets and paysheets => Sorting

Side loading items

If you want to retrieve the complete information about the items associated with the invoices, you can pass ?include=items in the url

Example:

GET /invoices?include=items

Getting an invoice

Example request

curl "https://getquipu.com/invoices/2988939" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": {
    "id": "2988939",
    "type": "invoices",
    "attributes": {
      "kind": "income",
      "number": "2016-2",
      "issue_date": "2016-02-29",
      "due_dates": ["2016-03-31"],
      "paid_at": "2016-03-02",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "total_amount": "2472.98",
      "total_amount_without_taxes": "2333.0",
      "vat_amount": "489.93",
      "retention_amount": "349.95"
      "issuing_name": "Paolo Conte",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "QuipuApp S.L.",
      "recipient_tax_id": "B66086042",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "es",
      "tags": "",
      "last_sent_at": 1457364458
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3399147"
        }]
      }
    }
  }
}

Example response with items included

{
  "data": {
    "id": "2988939",
    "type": "invoices",
    "attributes": {
      "kind": "income",
      "number": "2016-2",

      ... (some attrs omitted)

      "tags": ""
    },
    "relationships": {

      .... (some relationships omitted)

      "items": {
        "data": [{
          "id": "3298861",
          "type": "book_entry_items"
        }, {
          "id": "3298862",
          "type": "book_entry_items"
        }, {
          "id": "3298863",
          "type": "book_entry_items"
        }]
      }
    }
  },
  "included": [{
    "id": "3298861",
    "type": "book_entry_items",
    "attributes": {
      "concept": "T10 1 zona"
      "unitary_amount":"9.038"
      "quantity":"5.0"
      "vat_amount":"4.519"
      "retention_amount":"0.0"
      "total_amount":"49.709"
      "vat_percent":"10.0"
      "retention_percent":"0.0",
      "description": "item description"
    }
  }, {
    "id":"3298862"
    "type":"book_entry_items"
    "attributes": {
      "concept":"T10 2 zones"
      "unitary_amount":"17.82"
      "quantity":"19.0"
      "vat_amount":"33.858"
      "retention_amount":"0.0"
      "total_amount":"372.438"
      "vat_percent":"10.0"
      "retention_percent":"0.0",
      "description": "item description"
    }
  }, {
    "id":"3298863"
    "type":"book_entry_items"
    "attributes": {
      "concept":"T50/30 1 zona"
      "unitary_amount":"38.64"
      "quantity":"1.0"
      "vat_amount":"3.864"
      "retention_amount":"0.0"
      "total_amount":"42.504"
      "vat_percent":"10.0"
      "retention_percent":"0.0",
      "description": "item description"
    }
  }]
}

GET /invoices/:invoice_id

Creating an invoice

Example request

curl "https://getquipu.com/invoices" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "attributes": {
            "kind": "income",
            "number": null,
            "issue_date": "2016-03-12",
            "due_dates": ["2016-05-12"],
            "paid_at": null,
            "payment_method": "bank_transfer",
            "tags": "songo, timba"
          },
          "relationships": {
            "contact": {
              "data": {
                "id": 6347,
                "type": "contacts"
              }
            },
            "accounting_category": {
              "data": {
                "id": 123,
                "type": "accounting_categories"
              }
            },

            ...

            "items": {
              "data": [{
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Tornillos",
                  "unitary_amount": "0.50",
                  "quantity": 30,
                  "vat_percent": 21,
                  "retention_percent": 0
                }
              }, {
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Tuercas",
                  "unitary_amount": "0.35",
                  "quantity": 30,
                  "vat_percent": 21,
                  "retention_percent": 0
                }
              }]
            }
          }
        }
      }'

POST /invoices

About items

The way we send info about the items associated to a book entry is not compliant with the JSON API format. We do it this way because this resource (book entry items) are an essential part of a book entry, and to save some api calls. In brief, when sending data about the items we add the info in relationships => items => data => attributes, but in the responses we will find the details about items in the includes object.

Updating an invoice

Example request

curl "https://getquipu.com/invoices/2988939" \
  -X PATCH \
  -H "Authorization: Bearer 818abe1ea4a1813999a47105892d50f3781320c588fb8cd2927885963e621228" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "id": 2988939,
          "attributes": {
            "issue_date": "2016-02-21"
          }
        }
      }'

(PUT|PATCH) /invoices/:invoice_id

Deleting an invoice

Example request

curl "https://getquipu.com/invoices/2988939" \
  -X DELETE
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

DELETE /invoices/:invoice_id

Refunds and credit notes

An invoice can be totally or partially amended, resulting in a credit note. To create a complete credit note for an invoice, the minimal required data is the relationship amended_invoice. This will generate a full refund for the original invoice.

To partially amend an invoice, you can manually set the items of the credit note.

Example request for a complete refund

curl "https://getquipu.com/invoices" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "relationships": {
            "amended_invoice": {
              "data": {
                "id": 879495,
                "type": "invoices"
              }
            }
          }
        }
      }'

Example of a partial refund

curl "https://getquipu.com/invoices" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "relationships": {
            "amended_invoice": {
              "data": {
                "id": 879495,
                "type": "invoices"
              }
            },
            "items": {
              "data": [{
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Partial refund for service delay",
                  "quantity": 1,
                  "unitary_amount": "-5.00",
                  "vat_percent": 21
                }
              }]
            }
          }
        }
      }'

Tickets

Endpoints to manage tickets (receipts).

The main difference between invoices and tickets is that the latest don’t have an associated contact. You provide only the counterpart name: the issuing_name for expense tickets or the recipient_name for income tickets

Attributes

Attr. name	Constraints
kind	REQUIRED Accepted values: income or expenses
number	For income tickets we recommend leave it blank, and Quipu will assign it. For income tickets must be unique within a fiscal year.
issue_date	REQUIRED Format: YYYY-mm-dd
paid_at	Format: YYYY-mm-dd
payment_method	Accepted valued: cash, bank_transfer, bank_card, direct_debit, paypal, check, factoring
payment_status	READ ONLY
total_amount	READ ONLY
total_amount	READ ONLY
total_amount_without_taxes	READ ONLY
vat_amount	READ ONLY
retention_amount	READ ONLY
issuing_name	REQUIRED for expense tickets. READ ONLY for income tickets. *
issuing_tax_id	READ ONLY, *
issuing_address	READ ONLY, *
issuing_phone	READ ONLY, *
issuing_town	READ ONLY, *
issuing_zip_code	READ ONLY, *
issuing_country_code	READ ONLY, *
recipient_name	REQUIRED for income tickets. READ ONLY for expense tickets. *
recipient_tax_id	READ ONLY, *
recipient_address	READ ONLY, *
recipient_phone	READ ONLY, *
recipient_town	READ ONLY, *
recipient_zip_code	READ ONLY, *
recipient_country_code	READ ONLY, *
tags	Format: a list of strings separated by comma
notes	Format: a string
download_pdf_url	Url to download the pdf document for the ticket. Present only in income tickets. Needs the same authorization header.
download_pdf_url	Url to download the pdf document for the invoice. Present only in income tickets. Needs the same authorization header.

* This fields will be populated and updated each time an invoice is saved from the information of the Quipu account owner and the contact associatied with the book entry.

Relationships

Relationship name	Constraints
accounting_category
accounting_subcategory
numeration	Applicable only to tickets with kind = income
analytic_categories	Can not be a root analytic category
items	Can be sideloaded in GET requests. Must be included in the payload in POST/PATCH/PUT requests
amended_ticket	The ticket amended by the current one.
amending_tickets	Ticket that amends the current one (Read Only)

Listing tickets

Example request

curl "https://getquipu.com/tickets" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "2988939",
    "type": "tickets",
    "attributes": {
      "kind": "income",
      "number": "t16-53",
      "issue_date": "2016-02-29",
      "paid_at": "2016-03-02",
      "payment_method": "cash",
      "payment_status": "paid",
      "total_amount": "5.40",
      "total_amount_without_taxes": "4.46",
      "vat_amount": "0.94",
      "retention_amount": "0.0"
      "issuing_name": "QuipuApp S.L.",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "Manolo",
      "recipient_tax_id": "",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6332"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3399147"
        }]
      }
    }
  }, {
    "id": "2937714",
    "type": "tickets",
    "attributes": {
      "kind": "income",
      "number": "t16-53",
      "issue_date": "2016-01-31",
      "paid_at": "2016-02-03",
      "payment_method": "cash",
      "payment_status": "paid",
      "total_amount": "5.40",
      "total_amount_without_taxes": "4.46",
      "vat_amount": "0.94",
      "retention_amount": "0.0"
      "issuing_name": "QuipuApp S.L.",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "Manolo",
      "recipient_tax_id": "",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data": []
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3319559"
        }]
      }
    }
  }, {

  ...

  },
  "meta": {
    pagination_info: {
      "total_pages": 2
      "current_page": 1
      "total_results": 23
    }
  }
}

GET /tickets

Available filters

See Invoices, tickets and paysheets => Available filters

Sorting

See Invoices, tickets and paysheets => Sorting

Side loading items

If you want to retrieve the complete information about the items associated with the tickets, you can pass ?include=items in the url

Example:

GET /tickets?include=items

Getting a ticket

Example request

curl "https://getquipu.com/tickets/2989809" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": {
    "id": "2989809",
    "type": "tickets",
    "attributes": {
      "kind": "income",
      "number": "t16-53",
      "issue_date": "2016-02-29",
      "paid_at": "2016-03-02",
      "payment_method": "cash",
      "payment_status": "paid",
      "total_amount": "5.40",
      "total_amount_without_taxes": "4.46",
      "vat_amount": "0.94",
      "retention_amount": "0.0"
      "issuing_name": "QuipuApp S.L.",
      "issuing_tax_id": "43467890F",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "Manolo",
      "recipient_tax_id": "",
      "recipient_address": "",
      "recipient_phone": "",
      "recipient_town": "",
      "recipient_zip_code": "",
      "recipient_country_code": "",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "133"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6332"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "items": {
        "data": [{
          "type": "book_entry_items",
          "id": "3399147"
        }]
      }
    }
  }
}

GET /tickets/:ticket_id | GET /tickets/:ticket_id?include=items

Creating a ticket

Example request

curl "https://getquipu.com/tickets" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "tickets",
          "attributes": {
            "kind": "income",
            "number": null,
            "recipient_name": "unknown",
            "issue_date": "2016-03-08",
            "paid_at": "2016-03-08",
            "payment_method": "cash",
            "tags": "songo, timba"
          },
          "relationships": {
            "accounting_category": {
              "data": {
                "id": 123,
                "type": "accounting_categories"
              }
            },

            ...

            "items": {
              "data": [{
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Tornillos",
                  "unitary_amount": "0.50",
                  "quantity": 30,
                  "vat_percent": 21,
                  "retention_percent": 0
                }
              }, {
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Tuercas",
                  "unitary_amount": "0.35",
                  "quantity": 30,
                  "vat_percent": 21,
                  "retention_percent": 0
                }
              }]
            }
          }
        }
      }'

POST /tickets

Updating a ticket

Example request

# This request will update the attributes of the item with id 23424141,
# create a new item with concept "Tuercas",
# and destroy other items associated to the ticket if any.

curl "https://getquipu.com/tickets/2682381" \
  -X PATCH \
  -H "Authorization: Bearer 818abe1ea4a1813999a47105892d50f3781320c588fb8cd2927885963e621228" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "id": 2682381,
          "attributes": {
            "paid_at": "21-2-2016"
          },
          "relationships": {
            "items": {
              "data": [{
                "id": 23424141,
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Tornillos",
                  "unitary_amount": "0.50",
                  "quantity": 30,
                  "vat_percent": 21,
                  "retention_percent": 0
                }
              }, {
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Tuercas",
                  "unitary_amount": "0.35",
                  "quantity": 30,
                  "vat_percent": 21,
                  "retention_percent": 0
                }
              }]
            }
          }
        }
      }'

(PUT|PATCH) /tickets/:ticket_id

Deleting a ticket

Example request

curl "https://getquipu.com/tickets/2988939" \
  -X DELETE
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

DELETE /tickets/:ticket_id

Refunds and amending tickets

A ticket can be totally or partially amended. The minimal amount of data needed to create an amending ticket is the relationship amended_ticket. With this data a complete refund of the original ticket will be created.

You can also partially amend a ticket setting the items of the amending ticket manually.

Example request for a complete refund

curl "https://getquipu.com/tickets" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "tickets",
          "relationships": {
            "amended_ticket": {
              "data": {
                "id": 879495,
                "type": "tickets"
              }
            }
          }
        }
      }'

Example of a partial refund

curl "https://getquipu.com/tickets" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "tickets",
          "relationships": {
            "amended_ticket": {
              "data": {
                "id": 879495,
                "type": "tickets"
              }
            },
            "items": {
              "data": [{
                "type": "book_entry_items",
                "attributes": {
                  "concept": "Partial refund for service delay",
                  "quantity": 1,
                  "unitary_amount": "-5.00",
                  "vat_percent": 21
                }
              }]
            }
          }
        }
      }'

Items

There aren’t specific endpoints to manage items. Items are always associated to an invoice or ticket and should be manipulated through it.

Attributes

Attr. name	Constraints
id	Read only
concept
unitary_amount
quantity
kind	Must be current or assets (*) for items associated to expenses. Must be current or reimbursement (**) for items associated to income. Default is current
vat_percent	Percentage. Between 0 and 100
retention_percent	Percentage. Between 0 and 100
discount_percent	Percentage. Between 0 and 100
deductible_vat_percent	Percentage. Between 0 and 100
deductible_expense_percent	Percentage. Between 0 and 100
description	String. Item description
vat_amount	Read only
retention_amount	Read only
discount_amount	Read only
decuctible_vat_amount	Read only
total_amount	Read only

* Items with kind assets:

** Items with kind reimbursement:

Paysheets

Endpoints to manage paysheets

Attributes

Attr. name	Constraints
kind	READ ONLY. Always expenses
number	We recommend leave it blank, and Quipu will assign it. Must be unique within a fiscal year.
issue_date	REQUIRED Format: YYYY-mm-dd
paid_at	Format: YYYY-mm-dd
payment_method	Accepted valued: cash, bank_transfer, bank_card, direct_debit, paypal, check, factoring
payment_status	READ ONLY
net_pay
gross_pay	READ ONLY
employee_ss_amount
employee_retention
company_ss_amount
issuing_name	READ ONLY, *
issuing_tax_id	READ ONLY, *
issuing_address	READ ONLY, *
issuing_phone	READ ONLY, *
issuing_town	READ ONLY, *
issuing_zip_code	READ ONLY, *
issuing_country_code	READ ONLY, *
recipient_name	READ ONLY, *
recipient_tax_id	READ ONLY, *
recipient_address	READ ONLY, *
recipient_phone	READ ONLY, *
recipient_town	READ ONLY, *
recipient_zip_code	READ ONLY, *
recipient_country_code	READ ONLY, *
tags	Format: a list of strings separated by comma

* This fields will be populated and updated each time a paysheet is saved from the information of the Quipu account owner and the contact associatied with the paysheet.

Relationships

Relationship name	Constraints
contact	REQUIRED
accounting_category	READ ONLY
accounting_subcategory
analytic_categories	Can not be a root analytic category

Listing paysheets

Example request

curl "https://getquipu.com/paysheets" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "3007641",
    "type": "paysheets",
    "attributes": {
      "kind": "expenses",
      "number": "N-18",
      "issue_date": "2016-01-30",
      "paid_at": "2016-02-05",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "net_pay": "1185.76",
      "gross_pay": "1387.5",
      "employee_ss_amount": "88.8",
      "employee_retention": "112.94",
      "company_ss_amount": "450.25",
      "issuing_name": "QuipuApp S.L.",
      "issuing_tax_id": "B66086042",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "Kunta Kinte",
      "recipient_tax_id": "43429713D",
      "recipient_address": "C/ Gambia, 72, entlo-4a",
      "recipient_phone": "999999999",
      "recipient_town": "Hospitalet de Llobregat",
      "recipient_zip_code": "08199",
      "recipient_country_code": "es",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "28"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6332"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      }
    }
  }, {
    "id": "3007642",
    "type": "paysheets",
    "attributes": {
      "kind": "expenses",
      "number": "N-19",
      "issue_date": "2016-01-30",
      "paid_at": "2016-02-05",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "net_pay": "1185.76",
      "gross_pay": "1387.5",
      "employee_ss_amount": "88.8",
      "employee_retention": "112.94",
      "company_ss_amount": "450.25",
      "issuing_name": "QuipuApp S.L.",
      "issuing_tax_id": "B66086042",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "Kunta Kinte",
      "recipient_tax_id": "43429713D",
      "recipient_address": "C/ Gambia, 72, entlo-4a",
      "recipient_phone": "999999999",
      "recipient_town": "Hospitalet de Llobregat",
      "recipient_zip_code": "08199",
      "recipient_country_code": "es",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "28"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6326"
        }
      },
      "analytic_categories": {
        "data": []
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      }
    }
  }, {

  ...

  },
  "meta": {
    pagination_info: {
      "total_pages": 2
      "current_page": 1
      "total_results": 23
    }
  }
}

GET /paysheets

Getting a paysheet

Example request

curl "https://getquipu.com/paysheets/3007642" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": {
    "id": "3007641",
    "type": "paysheets",
    "attributes": {
      "kind": "expenses",
      "number": "N-18",
      "issue_date": "2016-01-30",
      "paid_at": "2016-02-05",
      "payment_method": "bank_transfer",
      "payment_status": "paid",
      "net_pay": "1185.76",
      "gross_pay": "1387.5",
      "employee_ss_amount": "88.8",
      "employee_retention": "112.94",
      "company_ss_amount": "450.25",
      "issuing_name": "QuipuApp S.L.",
      "issuing_tax_id": "B66086042",
      "issuing_address": "C/ Viladomat 39",
      "issuing_phone": "123456789",
      "issuing_town": "San Cucufate",
      "issuing_zip_code": "09876",
      "issuing_country_code": "es",
      "recipient_name": "Kunta Kinte",
      "recipient_tax_id": "43429713D",
      "recipient_address": "C/ Gambia, 72, entlo-4a",
      "recipient_phone": "999999999",
      "recipient_town": "Hospitalet de Llobregat",
      "recipient_zip_code": "08199",
      "recipient_country_code": "es",
      "tags": ""
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "type": "accounting_categories",
          "id": "28"
        }
      },
      "accounting_subcategory": {
        "data": null
      },
      "numeration": {
        "data": {
          "type": "numbering_series",
          "id": "6332"
        }
      },
      "analytic_categories": {
        "data":[]
      },
      "contact": {
        "data": {
          "type": "contacts",
          "id": "621291"
        }
      }
    }
  }
}

GET /paysheets/:paysheet_id

Creating a paysheet

Example request

curl "https://getquipu.com/paysheets" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "paysheets",
          "attributes": {
            "issue_date": "2016-03-12",
            "net_pay": "1185.76",
            "employee_ss_amount": "88.8",
            "employee_retention": "112.94",
            "company_ss_amount": "450.25",
            "tags": "songo, timba"
          },
          "relationships": {
            "contact": {
              "data" {
                "id": 6347,
                "type": "contacts"
              }
            },
            "analytic_categories": {
              ...
            },
            "accounting_subcategories": {
              ...
            },
            "numeration": {
              ...
            }
          }
        }
      }'

POST /paysheets

Updating a paysheet

Example request

curl "https://getquipu.com/paysheets/462380" \
  -X PATCH
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "id": 462380,
          "type": "paysheets",
          "attributes": {
            "net_pay": "1185.76",
            "employee_ss_amount": "88.8",
            "employee_retention": "112.94",
            "company_ss_amount": "450.25",
            "tags": ""
          },
        }
      }'

(PATCH/PUT) /paysheets/:paysheet_id

Deleting a paysheet

Example request

curl "https://getquipu.com/paysheets/2988939" \
  -X DELETE
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

DELETE /paysheets/:paysheet_id

Numbering series

The numbering series are applicable only to income tickets and invoices.

Attributes

Attr. name	Constraints
prefix	REQUIRED. Must be unique. The prefix that will be preppended to the invoice, or ticket
applicable_to	REQUIRED. Accepted values: "tickets" or "invoices"
default	Accepted values: true or false. Used only in the fronted when creating a new income invoice or ticket.
amending	Accepted values: true or false. Indicates if the series is applicable to amendig tickets or invoices
deletable	READ ONLY. Indicates if the numeration can be deleted. If there are invoices or tickets using a numeration this numeration can not be deleted

Listing the numbering series

Example request

curl "https://getquipu.com/numbering_series" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "6326",
    "type": "numbering_series",
    "attributes": {
      "prefix": "2016",
      "deletable": false,
      "default": true,
      "amending": false,
      "applicable_to": "invoices"
    }, {
    "id": "6332",
    "type": "numbering_series",
    "attributes": {
      "prefix": "AT16",
      "deletable": false,
      "default": false,
      "amending": true,
      "applicable_to": "tickets"
    }
  }]
}

GET /numbering_series

Available filters

Filter name	Description	Valid values	Example
prefix	Searh numbering series by prefix. Substring search. Case insensitive.	A string	?filter[prefix]=FC16
applicable_to	Filters by the kind of document the series is applicable to	invoices, tickets, budgets	?filter[applicable_to]=invoices
amending	Filters the series by whether they are applicable to amending documents	true, false	?filter[amending]=false

Getting a numbering serie

Example request

curl "https://getquipu.com/numbering_series/6326" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": {
    "id": "6326",
    "type": "numbering_series",
    "attributes": {
      "prefix": "2016",
      "deletable": false,
      "default": true,
      "amending": false,
      "applicable_to": "invoices"
    }
  }
}

GET /numbering_series/:numbering_series_id

Creating a numbering series

Example request

curl "https://getquipu.com/numbering_series" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "numbering_series",
          "attributes": {
            "prefix": "AIT",
            "applicable_to": "invoices",
            "amending": false,
            "default": false
          }
        }
      }'

POST /numbering_series/:numbering_series_id

Updating a numbering series

Example request

curl "https://getquipu.com/numbering_series/3412" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "id": "3412",
          "type": "numbering_series",
          "attributes": {
            "default": true
          }
        }
      }'

(PUT|PATCH) /numbering_series/:numbering_series_id

Deleting a numbering series

The server will respond with 403: Unauthorized if the numeration can not be deleted

Example request

curl "https://getquipu.com/numbering_series/3412" \
  -X DELETE
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

DELETE /numbering_series/:numbering_series_id

Analytic categories

Accounting categories

Attributes

Attr. name	Constraints
prefix	READ ONLY
name	READ ONLY
kind	READ ONLY. income, expenses or assets

Listing accounting categories

Example request

curl "https://getquipu.com/accounting_categories" \
  -H "Authorization: Bearer 818abe1ea4a1813999a47105892d50f3781320c588fb8cd2927885963e621228" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "234",
    "type": "accounting_categories",
    "attributes": {
      "name": "Gastos de investigación",
      "prefix": 200,
      "kind": "assets"
    }
  }, {
    "id": "235",
    "type": "accounting_categories",
    "attributes": {
      "name": "Desarrollo",
      "prefix": 201,
      "kind": "assets"
      }
  }, {
    "id": "236",
    "type": "accounting_categories",
    "attributes": {
      "name": "Concesiones administrativas",
      "prefix": 202,
      "kind": "assets"
    }
  }, {
    "id": "237",
    "type": "accounting_categories",
    "attributes": {
      "name": "Propiedad industrial",
      "prefix": 203,
      "kind": "assets"
    }
  }, {
    "id": "238",
    "type": "accounting_categories",
    "attributes": {
      "name": "Fondo de comercio",
      "prefix": 204,
      "kind": "assets"
    }
  }, {
    "id": "239",
    "type": "accounting_categories",
    "attributes": {
      "name": "Derechos de traspaso",
      "prefix": 205,
      "kind": "assets"
    }
  },

  ...

}

GET /accounting_categories

Available filters

Filter name	Description	Valid values	Example
kind	Filter resources by kind	expenses, income, or assets	/accounting_categories?filter[kind]=expenses
prefix	filter categories with the given accounting numbers	List of prefixes separated by comma	/accounting_categories?filter[prefix]=601,603,608

Getting an accounting category

Example request

curl "https://getquipu.com/accounting_categories/132" \
  -H "Authorization: Bearer 818abe1ea4a1813999a47105892d50f3781320c588fb8cd2927885963e621228" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "132",
    "type": "accounting_categories",
    "attributes": {
      "name": "Ventas de mercaderías",
      "prefix": 700,
      "kind": "income"
    }
  }
}

GET /accounting_categories/:accounting_category_id

Accounting subcategories

Attributes

Attr. name	Constraints
suffix	REQUIRED. Must be unique within an accounting category
name	REQUIRED

Relationships

Relationship name	Constraints
accounting_category	REQUIRED

Listing accounting subcategories

Example request

curl "https://getquipu.com/accounting_subcategories" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": [{
    "id": "19482",
    "type": "accounting_subcategories",
    "attributes": {
      "name": "Oficina",
      "suffix": 1
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "id": "43",
          "type": "accounting_categories"
        }
      }
    }
  }, {
    "id": "19483",
    "type": "accounting_subcategories",
    "attributes": {
      "name": "Raw",
      "suffix": 2
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "id": "43",
          "type": "accounting_categories"
        }
      }
    }
  }, {

  ...

  }]
}

GET /accounting_subcategories

Available filters

You can filter accounting subcategories by its accounting category id by passing an array of comma separated ids, for example GET /accounting_subcategories?filter[accounting_category_id]=43,44,48.

Getting an accounting subcategory

Example request

curl "https://getquipu.com/accounting_subcategories/19482" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json"

Example response

{
  "data": {
    "id": "19482",
    "type": "accounting_subcategories",
    "attributes": {
      "name": "Oficina",
      "suffix": 1
    },
    "relationships": {
      "accounting_category": {
        "data": {
          "id": "43",
          "type": "accounting_categories"
        }
      }
    }
  }
}

GET /accounting_subcategories/:accounting_subcategory_id

Creating an accounting subcategory

Example request

curl "https://getquipu.com/accounting_subcategories" \
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "attributes": {
            "prefix": 2,
            "name": "Vestuario"
          },
          "relationships": {
            "accounting_category": {
              "data" {
                "id": 43,
                "type": "accounting_categories"
              }
            }
          }
        }
      }'

POST /accounting_subcategories

Updatinig an accounting subcategory

Example request

curl "https://getquipu.com/accounting_subcategories/19482" \
  -X PATCH
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \
  -H "Content-Type: application/vnd.quipu.v1+json" \
  -d '{
        "data": {
          "type": "invoices",
          "attributes": {
            "name": "Transporte"
          }
        }
      }'

(PUT|PATCH) /accounting_subcategories/:accounting_subcategory_id

Deleting an accounting subcategory

Example request

curl "https://getquipu.com/accounting_subcategories/19482" \
  -X DELETE
  -H "Authorization: Bearer be32259bd1d0f4d3d02bcc0771b1b507e2b666ba9e9ba3d7c5639e853f722eb4" \
  -H "Accept: application/vnd.quipu.v1+json" \

DELETE /accounting_subcategories/:accounting_subcategory_id

Attachments

Attributes

Attr. name	Constraints
url	The url for the file
small_url	Only if the file is an image. A version of the attachment scaled to fit 500 x 500 px.
thumbnail_url	Only if the file is an image. A version of the attachment scaled to fit 100 x 100 px.

Relationships

Relationship name	Constraints
book_entry	REQUIRED when uploading attachments. The invoice, ticket or paysheet that this attachment is related to

Uploading an attachment

Example request

curl "https://getquipu.com/attachments"
  -X POST \
  -H "Authorization: Bearer 4cbc2f18d5e7bcfb44f46c5ed72c5e94fd059f7f4d... " \
  -H "Accept: application/vnd.quipu.v1+json" \
  -F "file=@/path/to/the/file.jpg" \
  -F "book_entry_id=3308976"

Example response

{
  "data": {
    "id": "2311315",
    "type": "attachments",
    "attributes": {
      "url": "uploads/book_entry_attachments/2311315-36eb52a2959af9d2dcbddc356549b125/image.png",
      "small_url": "uploads/book_entry_attachments/2311315-36eb52a2959af9d2dcbddc356549b125/preview_image.png",
      "thumbnail_url": "uploads/book_entry_attachments/2311315-36eb52a2959af9d2dcbddc356549b125/thumbnail_image.png"
    },
    "relationships": {
      "book_entry": {
        "data": {
          "id": "3308976",
          "type": "invoices"
        }
      }
    }
  }
}

POST /attachments

Getting an attachment

Example request

curl "https://getquipu.com/attachments/2311315" \
  -H "Authorization: Bearer 4cbc2f18d5e7bcfb44f46c5ed72c5e94fd059f7f4d... " \
  -H "Accept: application/vnd.quipu.v1+json"

GET /attachments/:id

Example response

{
  "data": {
    "id": "2311315",
    "type": "attachments",
    "attributes": {
      "url": "uploads/book_entry_attachments/2311315-36eb52a2959af9d2dcbddc356549b125/image.png",
      "small_url": "uploads/book_entry_attachments/2311315-36eb52a2959af9d2dcbddc356549b125/preview_image.png",
      "thumbnail_url": "uploads/book_entry_attachments/2311315-36eb52a2959af9d2dcbddc356549b125/thumbnail_image.png"
    },
    "relationships": {
      "book_entry": {
        "data": {
          "id": "3308976",
          "type": "invoices"
        }
      }
    }
  }
}

Removing an attachment

DELETE /attachments/:id

curl "https://getquipu.com/attachments/2311315" \
  -X DELETE \
  -H "Authorization: Bearer 4cbc2f18d5e7bcfb44f46c5ed72c5e94fd059f7f4d... " \
  -H "Accept: application/vnd.quipu.v1+json"

TODO

• Improve error messages
• Add endpoint to send invoices via email
• Add endpoints to add attachments to invoices or tickets