API mantida por Fintera

Categorias (Category)

O recurso Category representa uma categoria ou subcategoria cadastrada em seu Financeiro. As categorias estão associadas diretamente à sua Account no Financeiro, isto é, são compartilhados entre todas as entidades (Entity) de sua conta no Financeiro.

As categorias podem ser associadas à outros objetos (FinancialTranscation e FinancialAccount) tanto através de seu id (seu código identificador único sistema) quanto através de seu nome completo (atributo full_name). Para tal, os nomes devem ser únicos no contexto do seu Financeiro.

Listar Categorias

GET /categories

Retorna uma lista (paginada) de todas as Categorias da Account que usuários possui acesso. Para designar o número de registros por página, passar o parâmetro per_page no endpoint. Caso o parâmetro não seja passado, o default de 50 será utilizado. O limite superior é de 500 registros por página. Para navegar entre as diferentes páginas, basta usar o parâmetro page. Exemplo:

GET /categories?per_page=15&page=3

O endpoint acima irá retornar a terceira página da listagem de Categorias com 15 registros em cada.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
Links: <https://financeiro.fintera.com.br/categories.xml?page=2&per_page=50>;rel="next",<https://financeiro.fintera.com.br/categories.xml?page=2&per_page=50>;rel="last"
<?xml version="1.0" encoding="UTF-8"?>
<categories type="array">
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:28-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Diversão</full-name>
    <id type="integer">5</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Diversão</name>
    <parent-id type="integer" nil="true"/>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:28-02:00</updated-at>
    <use-count type="integer">1</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:29-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Luxo</full-name>
    <id type="integer">6</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Luxo</name>
    <parent-id type="integer" nil="true"/>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:29-02:00</updated-at>
    <use-count type="integer">0</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:29-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Luxo / Veiculos</full-name>
    <id type="integer">7</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Veiculos</name>
    <parent-id type="integer">6</parent-id>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:29-02:00</updated-at>
    <use-count type="integer">1</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:23-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Moradia</full-name>
    <id type="integer">1</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Moradia</name>
    <parent-id type="integer" nil="true"/>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:23-02:00</updated-at>
    <use-count type="integer">0</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:24-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Moradia / Aluguel</full-name>
    <id type="integer">3</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Aluguel</name>
    <parent-id type="integer">1</parent-id>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:24-02:00</updated-at>
    <use-count type="integer">61</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:25-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Moradia / contas</full-name>
    <id type="integer">4</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>contas</name>
    <parent-id type="integer">1</parent-id>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:25-02:00</updated-at>
    <use-count type="integer">183</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:23-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Moradia / Lazer</full-name>
    <id type="integer">2</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Lazer</name>
    <parent-id type="integer">1</parent-id>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:23-02:00</updated-at>
    <use-count type="integer">61</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:29-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Proventos</full-name>
    <id type="integer">8</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Proventos</name>
    <parent-id type="integer" nil="true"/>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:29-02:00</updated-at>
    <use-count type="integer">0</use-count>
  </category>
  <category>
    <cost type="boolean">true</cost>
    <created-at type="dateTime">2012-10-31T11:59:29-02:00</created-at>
    <excel-import-id type="integer" nil="true"/>
    <force-destroy type="boolean">false</force-destroy>
    <full-name>Proventos / Salário</full-name>
    <id type="integer">9</id>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <name>Salário</name>
    <parent-id type="integer">8</parent-id>
    <revenue type="boolean">true</revenue>
    <updated-at type="dateTime">2012-10-31T11:59:29-02:00</updated-at>
    <use-count type="integer">1</use-count>
  </category>
</categories>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
Links: <https://financeiro.fintera.com.br/categories.xml?page=2&per_page=50>;rel="next",<https://financeiro.fintera.com.br/categories.xml?page=2&per_page=50>;rel="last"
[
  {
    "category": {
      "account_id": 1,
        "cost": true,
          "created_at": "2012-10-31T11:59:28-02:00",
            "excel_import_id": null,
            "force_destroy": false,
            "full_name": "Diversão",
            "guid": null,
            "id": 5,
            "imported_from_sync": false,
            "modified_by_sync": false,
            "name": "Diversão",
            "parent_id": null,
            "revenue": true,
            "updated_at": "2012-10-31T11:59:28-02:00",
            "use_count": 1
        }
    },
    {
      "category": {
        "account_id": 1,
          "cost": true,
            "created_at": "2012-10-31T11:59:29-02:00",
            "excel_import_id": null,
            "force_destroy": false,
            "full_name": "Luxo",
            "guid": null,
            "id": 6,
            "imported_from_sync": false,
            "modified_by_sync": false,
            "name": "Luxo",
            "parent_id": null,
            "revenue": true,
            "updated_at": "2012-10-31T11:59:29-02:00",
            "use_count": 0
        }
    },
    {
      "category": {
        "account_id": 1,
          "cost": true,
            "created_at": "2012-10-31T11:59:29-02:00",
            "excel_import_id": null,
            "force_destroy": false,
            "full_name": "Luxo / Veiculos",
            "guid": null,
            "id": 7,
            "imported_from_sync": false,
            "modified_by_sync": false,
            "name": "Veiculos",
            "parent_id": 6,
            "revenue": true,
            "updated_at": "2012-10-31T11:59:29-02:00",
            "use_count": 1
        }
    }
]

Exemplo de Busca Avançada

GET /categories?search[name]=category_name&search[parent_id_is_null]=1

Filtros disponíveis para Busca Avançada

- name               | Nome exato da Categoria a ser buscada
- name_contains      | Categorias por nome contendo o critério informado
- full_name          | Nome completo exato da categoria
- full_name_contains | Categorias por nome contendo o critério informado
- parent_id          | Categorias pelo id da categoria pai
- parent_is_null     | 0 para buscar somente subcategorias, 1 para buscar somente categorias pai

Exibir uma categoria

GET /categories/:id

Retorna os atributos da categoria (via id) com uma resposta 200 Ok.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
<?xml version="1.0" encoding="UTF-8"?>
<category>
  <cost type="boolean">true</cost>
  <created-at type="dateTime">2012-10-31T11:59:29-02:00</created-at>
  <excel-import-id type="integer" nil="true"/>
  <force-destroy type="boolean">false</force-destroy>
  <full-name>Proventos / Salário</full-name>
  <id type="integer">9</id>
  <imported-from-sync type="boolean">false</imported-from-sync>
  <modified-by-sync type="boolean">false</modified-by-sync>
  <name>Salário</name>
  <parent-id type="integer">8</parent-id>
  <revenue type="boolean">true</revenue>
  <updated-at type="dateTime">2012-10-31T11:59:29-02:00</updated-at>
  <use-count type="integer">1</use-count>
</category>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
{
  "category": {
    "cost": true, 
    "created_at": "2012-10-31T11:59:29-02:00", 
    "force_destroy": false, 
    "excel_import_id": null, 
    "full_name": "Proventos / Salário", 
    "id": 9, 
    "imported_from_sync": false,
    "modified_by_sync": false, 
    "name": "Salário", 
    "parent_id": 8, 
    "revenue": true, 
    "updated_at": "2012-10-31T11:59:29-02:00", 
    "use_count": 1
  }
}

Criar uma categoria

POST /categories

Cria uma nova categoria com os parâmetros passados. Em caso de sucesso, retorna 201 Created, juntamente com a URI da categoria criada no cabeçalho Location da resposta HTTP. Em caso de falha, retorna 422 Unprocessable entity juntamente com a descrição dos erros.

Exemplo de Requisição

{
  "category":{
    "name":"Categoria Tal",
  }
}
<category>
  <name>Categoria Tal</name>
</category>

Exemplo de Resposta

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/categories/111
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
{
  "category":{
    "cost":true,
    "created_at":"2012-11-07T17:05:53-02:00",
    "excel_import_id":null,
    "force_destroy":false,
    "full_name":"Categoria Tal",
    "id":73,
    "imported_from_sync":false,
    "modified_by_sync":false,
    "name":"Categoria Tal",
    "parent_id":null,
    "revenue":true,
    "updated_at":"2012-11-07T17:05:53-02:00",
    "use_count":0
  }
}
HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/categories/112
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<category>
  <cost type="boolean">true</cost>
  <created-at type="dateTime">2012-11-07T17:10:28-02:00</created-at>
  <excel-import-id type="integer" nil="true"></excel-import-id>
  <force-destroy type="boolean">false</force-destroy>
  <full-name>Categoria Tal</full-name>
  <id type="integer">73</id>
  <imported-from-sync type="boolean">false</imported-from-sync>
  <modified-by-sync type="boolean">false</modified-by-sync>
  <name>Categoria Tal</name>
  <parent-id type="integer" nil="true"></parent-id>
  <revenue type="boolean">true</revenue>
  <updated-at type="dateTime">2012-11-07T17:10:28-02:00</updated-at>
  <use-count type="integer">0</use-count>
</category>

Criar uma Subcategoria

POST categories/:id/create_subcategory

Cria uma nova subcategoria com os parâmetros passados. Em caso de sucesso, retorna 201 Created, juntamente com a URI da subcategoria criada no cabeçalho Location da resposta HTTP. Em caso de falha, retorna 422 Unprocessable entity juntamente com a descrição dos erros.

Exemplo de Requisição

{
  "category":{
    "name":"Subcategoria Tal"
  }
}
<category>
  <name>Subcategoria Tal</name>
</category>

Exemplo de Resposta

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/categories/111
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
{
  "category":{
    "cost":true,
    "created_at":"2012-11-07T17:05:53-02:00",
    "excel_import_id":null,
    "force_destroy":false,
    "full_name":"Categoria Tal / Subcategoria Tal",
    "id":73,
    "imported_from_sync":false,
    "modified_by_sync":false,
    "name":"Subcategoria Tal",
    "parent_id":null,
    "revenue":true,
    "updated_at":"2012-11-07T17:05:53-02:00",
    "use_count":0
  }
}
HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/categories/112
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<category>
  <cost type="boolean">true</cost>
  <created-at type="dateTime">2012-11-07T17:10:28-02:00</created-at>
  <excel-import-id type="integer" nil="true"></excel-import-id>
  <force-destroy type="boolean">false</force-destroy>
  <full-name>Categoria Tal / Subcategoria Tal</full-name>
  <id type="integer">74</id>
  <imported-from-sync type="boolean">false</imported-from-sync>
  <modified-by-sync type="boolean">false</modified-by-sync>
  <name>Subcategoria Tal</name>
  <parent-id type="integer" nil="true"></parent-id>
  <revenue type="boolean">true</revenue>
  <updated-at type="dateTime">2012-11-07T17:10:28-02:00</updated-at>
  <use-count type="integer">0</use-count>
</category>

Alterar uma categoria

Exemplo de Requisição

PUT /categories/:id

Altera a categoria especificada. Retorna uma resposta vazia 200 Ok em caso de sucesso ou uma resposta 422 Unprocessable entity com a descrição dos erros em caso de falha.

Apagar uma categoria

Exemplo de Requisição

DELETE /categories/:id

Apaga a categoria especificada, retornando uma resposta vazia com status 200 Ok. Em caso de sucesso, todos os recursos previamente associados ao categoria apagado continuarão existindo, porém não estarão associados a nenhum categoria!