API mantida por Fintera

Entidades (Entity)

Uma entidade representa uma unidade organizacional e ela pode ser uma pessoa jurídica ou uma pessoa física.

Toda Account tem no mínimo uma entidade. Os usuários que quiserem administrar empresas diferentes, ou separar a gestão financeira entre matriz e filiais, por exemplo, usarão entidades diferentes. A maior parte dos recursos (endpoints) da API estarão aninhados à uma entidade específica, como por exemplo as Contas (DepositAccount), Lançamentos (FinancialTransaction), Contas a Pagar (PayableAccount), etc.

Listar entidades 

GET /entities

Retorna uma lista de todas as entidades da Account.

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"?>
<entities type="array">
  <entity>
    <created-at type="dateTime">2011-07-14T11:37:30-03:00</created-at>
    <federation-subscription-number nil="true"></federation-subscription-number>
    <force-destroy type="boolean">false</force-destroy>
    <account-id type="integer">1</account-id>
    <id type="integer">12</id>
    <name>Nova</name>
    <updated-at type="dateTime">2011-07-14T11:37:30-03:00</updated-at>
    <deleted-at type="dateTime" nil="true"></deleted-at>
  </entity>
  <entity>
    <created-at type="dateTime">2011-07-08T15:05:51-03:00</created-at>
    <federation-subscription-number>11111111111</federation-subscription-number>
    <force-destroy type="boolean">false</force-destroy>
    <id type="integer">1</id>
    <name>Minhas Finanças</name>
    <updated-at type="dateTime">2011-07-14T15:13:43-03:00</updated-at>
    <deleted-at type="dateTime" nil="true"></deleted-at>
  </entity>
</entities>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
[
  {
    "entity":
      {
        "created_at":"2011-07-14T11:37:30-03:00",
        "federation_subscription_number":"",
        "force_destroy":false,"id":12,
        "name":"Nova",
        "updated_at":"2011-07-14T11:37:30-03:00",
        "deleted_at":null
      }
  },
  {
    "entity":
      {
        "created_at":"2011-07-08T15:05:51-03:00",
        "federation_subscription_number":"11111111111",
        "force_destroy":false,
        "account_id":1,
        "id":1,
        "name":"Minhas Finanças",
        "updated_at":"2011-07-14T15:13:43-03:00",
        "deleted_at":null
      }
  }
]

Exemplo de Busca Avançada

GET /entities?search[name]=entity_name

Filtros disponíveis para Busca Avançada

- name                                     | Nome exato da Entidade a ser buscada
- name_contains                            | Entidades por nome contendo o critério informado
- federation_subscription_number_equals    | CPF ou CNPJ, com ou sem formatação de forma exata
- federation_subscription_number_contains  | CPF ou CNPJ, com ou sem formatação
- federation_subscription_number_is_null   | CPF e CNPJ é nulo

Exibir uma entidade

GET /entities/:id

Retorna os atributos da entidade especificada 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"?>
<entity>
  <created-at type="dateTime">2011-07-08T15:05:51-03:00</created-at>
  <federation-subscription-number>11111111111</federation-subscription-number>
  <force-destroy type="boolean">false</force-destroy>
  <account-id type="integer">1</account-id>
  <id type="integer">42</id>
  <name>Minhas Finanças</name>
  <updated-at type="dateTime">2011-07-14T15:13:43-03:00</updated-at>
  <deleted-at type="dateTime" nil="true"></deleted-at>
</entity>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
{
  "entity":
  {
    "id":42,
    "account_id":1,
    "created_at":"2011-07-08T15:05:51-03:00",
    "federation_subscription_number":"11111111111",
    "force_destroy":false,"id":1,"name":"Minhas Finanças",
    "updated_at":"2011-07-14T15:13:43-03:00",
    "deleted_at":null
  }
}

Exibir modelo de nova entidade

Exemplo de Requisição

GET /entities/new

Retorna os atributos de uma nova entidade, com os valores default. Use como modelo para criar novas entidades.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
{
  "entity":
  {
    "account_id":1,
    "created_at":null,
    "federation_subscription_number":null,
    "force_destroy":false,
    "name":null,
    "updated_at":null
  }
}
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"?>
<entity>
  <account-id type="integer">1</account-id>
  <name nil="true"></name>
  <created-at type="dateTime" nil="true"></created-at>
  <updated-at type="dateTime" nil="true"></updated-at>
  <federation-subscription-number nil="true"></federation-subscription-number>
</entity>

Criar uma entidade

POST /entities

Cria uma nova entidade com os parâmetros passados. Em caso de sucesso, retorna 201 Created, juntamente com a URI da entidade 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

{"entity": {"name": "Daily Bugle"}}
<entity>
  <name> Daily Bugle </name>
</entity>

Exemplo de Resposta

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/entities/111
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
{
  "entity":
    {
      "account_id":1,
      "created_at":"2011-07-14T16:10:15-03:00",
      "federation_subscription_number":null,
      "force_destroy":false,
      "id":14,
      "name":"Coisas",
      "updated_at":"2011-07-14T16:10:15-03:00",
      "deleted_at":null
    }
}
HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/entities/111
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<entity>
  <created-at type="dateTime">2011-07-14T15:42:51-03:00</created-at>
  <federation-subscription-number nil="true"></federation-subscription-number>
  <force-destroy type="boolean">false</force-destroy>
  <account-id type="integer">1</account-id>
  <id type="integer">13</id>
  <name> Daily Bugle </name>
  <updated-at type="dateTime">2011-07-14T15:42:51-03:00</updated-at>
  <deleted-at type="dateTime" nil="true"></deleted-at>
</entity>

Alterar uma entidade

PUT /entities/:id

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

Exemplo de Requisição

{"entity": {"name": "Daily Bugle"}}
<entity>
  <name> Daily Bugle </name>
</entity>

Exemplo de Resposta

HTTP/1.1 200 OK
Location: https://financeiro.fintera.com.br/entities/111
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
{
  "entity":
    {
      "account_id":1,
      "created_at":"2011-07-14T16:10:15-03:00",
      "federation_subscription_number":null,
      "force_destroy":false,
      "id":14,
      "name":"Coisas",
      "updated_at":"2011-07-14T16:10:15-03:00",
      "deleted_at":null
    }
}
HTTP/1.1 200 OK
Location: https://financeiro.fintera.com.br/entities/111
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<entity>
  <created-at type="dateTime">2011-07-14T15:42:51-03:00</created-at>
  <federation-subscription-number nil="true"></federation-subscription-number>
  <force-destroy type="boolean">false</force-destroy>
  <account-id type="integer">1</account-id>
  <id type="integer">13</id>
  <name> Daily Bugle </name>
  <updated-at type="dateTime">2011-07-14T15:42:51-03:00</updated-at>
  <deleted-at type="dateTime" nil="true"></deleted-at>
</entity>

Apagar uma entidade

Exemplo de Requisição

DELETE /entities/:id

Apaga a entidade especificada, retornando uma resposta vazia com status 202 Accepted. Todos os recursos associados à entidade apagada também serão apagados!

A exclusão é feita em background. Enquanto a exclusão não tiver sido concluída, a entidade continuará constando na lista de entidades da conta (em uma chamada à GET /entities por exemplo), porém virá com o atributo deleted_at preenchido com a data-hora do momento da solicitação da exclusão.

A última entidade de uma Account não pode ser excluída. Caso tente excluir a última entidade de uma Account, receberá uma resposta de erro 422 Unprocessable entity com uma resposta no body '{"base":["S\u00f3 existe uma entidade.","N\u00e3o \u00e9 poss\u00edvel apagar esta entidade."]}'.

Outros erros também acontecem com o mesmo status, só mudando as mensagens, que são: "Existem Contas que precisam ser apagadas.", "Existem Contas a Pagar/Contas a Receber que precisam ser apagadas" e "Existem Centro de Custo/Receita que precisam ser apagados.".

Se for passado como parâmetro { "force_destroy": "true" }, ele vai ignorar os possíveis erros e irá destruir o objeto.