Clientes / Fornecedores (`Person`)

Alterar um cliente / fornecedor
Apagar um cliente / fornecedor

O recurso Person representa um cliente e/ou fornecedor cadastrado em seu Financeiro. Os clientes / fornecedores estão associados diretamente à sua Account no Financeiro, isto é, são compartilhados entre todas as entidades (Entity) de sua conta no Financeiro.

Os clientes / fornecedores podem ser associados à outros objetos (FinancialTranscation e FinancialAccount) tanto através de seu id (seu código identificador único no sistema) quanto através de seus nomes (attributo name). Para tal, os nomes devem ser únicos no contexto do seu Financeiro.

Listar clientes / fornecedores

GET /people

Retorna uma lista (paginada) de todas as clientes / fornecedores 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 /people?per_page=15&page=3

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

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/people.xml?page=2&per_page=50>;rel="next",<https://financeiro.fintera.com.br/people.xml?page=2&per_page=50>;rel="last"

<?xml version="1.0" encoding="UTF-8"?>
<people type="array">
  <person>
    <account-id type="integer">40</id>
    <id type="integer">59</id>
    <name>ACME Corporation Inc.</name>
    <address nil="true"></address>
    <address-number nil="true"></address_number>
    <city nil="true"></city>
    <complement nil="true"></complement>
    <country nil="true"></country>
    <created-at type="dateTime">2011-03-23T17:01:58-03:00</created-at>
    <customer type="boolean">false</customer>
    <email nil="true"></email>
    <excel-import-id type="integer" nil="true"></excel-import-id>
    <federation-subscription-number nil="true"></federation-subscription-number>
    <federation-subscription-number-only-numbers nil="true"></federation-subscription-number-only-numbers>
    <federation-subscription-type-id type="integer" nil="true"></federation-subscription-type-id>
    <force-destroy type="boolean">false</force-destroy>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <neighborhood nil="true"></neighborhood>
    <note nil="true"></note>
    <person-type>JuridicalPerson</person-type>
    <phone nil="true"></phone>
    <site nil="true"></site>
    <state nil="true"></state>
    <supplier type="boolean">true</supplier>
    <updated-at type="dateTime">2011-04-16T16:15:16-03:00</updated-at>
    <use-count type="integer">89</use-count>
    <zip-code nil="true"></zip-code>
    <bank-account nil="true"></bank-account>
  </person>
  <person>
    <account-id type="integer">40</id>
    <id type="integer">60</id>
    <name>Myfreecomm</name>
    <address nil="true"></address>
    <address_number nil="true"></address_number>
    <city nil="true"></city>
    <complement nil="true"></complement>
    <country nil="true"></country>
    <created-at type="dateTime">2011-03-23T17:02:52-03:00</created-at>
    <customer type="boolean">true</customer>
    <email nil="true"></email>
    <excel-import-id type="integer" nil="true"></excel-import-id>
    <federation-subscription-number nil="true"></federation-subscription-number>
    <federation-subscription-number-only-numbers nil="true"></federation-subscription-number-only-numbers>
    <federation-subscription-type-id type="integer" nil="true"></federation-subscription-type-id>
    <force-destroy type="boolean">false</force-destroy>
    <imported-from-sync type="boolean">false</imported-from-sync>
    <modified-by-sync type="boolean">false</modified-by-sync>
    <neighborhood nil="true"></neighborhood>
    <note nil="true"></note>
    <person-type>JuridicalPerson</person-type>
    <phone nil="true"></phone>
    <site nil="true"></site>
    <state nil="true"></state>
    <supplier type="boolean">true</supplier>
    <updated-at type="dateTime">2011-04-26T15:53:57-03:00</updated-at>
    <use-count type="integer">159</use-count>
    <zip-code nil="true"></zip-code>
    <bank-account>
      <account-digit>1</account-digit>
      <account-number>12332</account-number>
      <agency-digit>01</agency-digit>
      <agency-number>2323</agency-number>
      <bank-code>001</bank-code>
      <bank-name>Banco do Brasil S.A.</bank-name>
    </bank-account>
  </person>
</people>

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/people.json?page=2&per_page=50>;rel="next",<https://financeiro.fintera.com.br/people.json?page=2&per_page=50>;rel="last"

[
  {
    "person":{
      "account_id":40,
      "address":null,
      "address_number":null,
      "city":null,
      "complement":null,
      "country":null,
      "created_at":"2011-03-23T17:01:58-03:00",
      "customer":false,
      "email":null,
      "excel_import_id":null,
      "federation_subscription_number":null,
      "federation_subscription_number_only_numbers":null,
      "federation_subscription_type_id":null,
      "force_destroy":false,
      "guid":null,
      "id":59,
      "imported_from_sync":false,
      "modified_by_sync":false,
      "name":"ACME Corporation Inc.",
      "neighborhood":null,
      "note":null,
      "person_type":"JuridicalPerson",
      "phone":null,
      "site":null,
      "state":null,
      "supplier":true,
      "updated_at":"2011-04-16T16:15:16-03:00",
      "use_count":89,
      "zip_code":null,
      "bank_account":null
    }
  },
  {
    "person":{
      "account_id":40,
      "address":null,
      "address_number":null,
      "city":null,
      "complement":null,
      "country":null,
      "created_at":"2011-03-23T17:02:52-03:00",
      "customer":true,
      "email":null,
      "excel_import_id":null,
      "federation_subscription_number":null,
      "federation_subscription_number_only_numbers":null,
      "federation_subscription_type_id":null,
      "force_destroy":false,
      "guid":null,
      "id":60,
      "imported_from_sync":false,
      "modified_by_sync":false,
      "name":"Myfreecomm",
      "neighborhood":null,
      "note":null,
      "person_type":"JuridicalPerson",
      "phone":null,
      "site":null,
      "state":null,
      "supplier":true,
      "updated_at":"2011-04-26T15:53:57-03:00",
      "use_count":159,
      "zip_code":null,
      "bank_account": {
        "account_digit":"1",
        "account_number":"12332",
        "agency_digit":"01",
        "agency_number":"2323",
        "bank_code":"001",
        "bank_name":"Banco do Brasil S.A."
      }
    }
  }
]

Exemplo de Busca Avançada

__Campo_____________________________________|_Requerido_|_Descrição________________________________________________________
- account_id                                | yes       | Filtros por account_id, passe no header
- person_type_in                            | no        | usar: NaturalPerson ou JuridicalPerson, que é Pessoa Física, ou Pessoa Jurídica
- person_type_is_null                       | no        | person_type será nulo
- classification_in                         | no        | usar: supplier ou customer, que é Fornecedor, ou Cliente
- name_equals                               | no        | é o nome exato do Cliente / Fornecedor que será buscado
- name_contains                             | no        | é o nome mais próximo de Cliente / Fornecedor que será passado
- federation_subscription_number_equals     | no        | verifica o CPF e CNPJ, com ou sem formatação de forma exata
- federation_subscription_number_contains   | no        | verifica CPF e CNPJ, com ou sem formatação de forma aproximada
- federation_subscription_number_is_null    | no        | CPF e CNPJ é nulo
- phone_contains                            | no        | telefone de forma aproximada
- phone_is_null                             | no        | telefone é nulo
- email_contains                            | no        | email de forma aproximada
- email_is_null                             | no        | email é nulo
- site_contains                             | no        | site de forma aproximada
- site_is_null                              | no        | site é nulo
- address_contains                          | no        | endereço de forma aproximada
- address_is_null                           | no        | endereço é nulo
- complement_contains                       | no        | complemento de forma aproximada
- complement_is_null                        | no        | complemento é nulo
- city_contains                             | no        | cidade de forma aproximada
- city_is_null                              | no        | cidade é nulo
- state_contains                            | no        | estado de forma aproximada
- state_is_null                             | no        | estado é nulo
- country_contains                          | no        | país de forma aproximada
- country_is_null                           | no        | país é nulo
- zip_code_contains                         | no        | CEP de forma aproximada
- zip_code_is_null                          | no        | CEP é nulo
- note_contains                             | no        | nota de forma aproximada
- note_is_null                              | no        | nota é nulo
https://financeiro.fintera.com.br/people?search[name_contains]=banco&search[federation_subscription_number_contains]=&search[federation_subscription_number_is_null]=0

Exibir um cliente / fornecedor

GET /people/:id

Retorna os atributos do cliente / fornecedor especificado (via id) com uma resposta 200 Ok.

Exemplo de Resposta

JSON
XML

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"?>
<person>
  <account-id type="integer">40</account-id>
  <id type="integer">59</id>
  <name>ACME Corporation Inc.</name>
  <address nil="true"></address>
  <address_number nil="true"></address_number>
  <city nil="true"></city>
  <complement nil="true"></complement>
  <country nil="true"></country>
  <created-at type="dateTime">2011-03-23T17:01:58-03:00</created-at>
  <customer type="boolean">false</customer>
  <email nil="true"></email>
  <excel-import-id type="integer" nil="true"></excel-import-id>
  <federation-subscription-number nil="true"></federation-subscription-number>
  <federation-subscription-number-only-numbers nil="true"></federation-subscription-number-only-numbers>
  <federation-subscription-type-id type="integer" nil="true"></federation-subscription-type-id>
  <force-destroy type="boolean">false</force-destroy>
  <imported-from-sync type="boolean">false</imported-from-sync>
  <modified-by-sync type="boolean">false</modified-by-sync>
  <neighborhood nil="true"></neighborhood>
  <note nil="true"></note>
  <person-type>JuridicalPerson</person-type>
  <phone nil="true"></phone>
  <site nil="true"></site>
  <state nil="true"></state>
  <supplier type="boolean">true</supplier>
  <updated-at type="dateTime">2011-04-16T16:15:16-03:00</updated-at>
  <use-count type="integer">89</use-count>
  <zip-code nil="true"></zip-code>
  <bank-account>
    <account-digit>1</account-digit>
    <account-number>12332</account-number>
    <agency-digit>01</agency-digit>
    <agency-number>2323</agency-number>
    <bank-code>001</bank-code>
    <bank-name>Banco do Brasil S.A.</bank-name>
  </bank-account>
</person>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT

{
  "person":{
    "account_id":40,
    "address":null,
    "address_number":null,
    "city":null,
    "complement":null,
    "country":null,
    "created_at":"2011-03-23T17:01:58-03:00",
    "customer":false,
    "email":null,
    "excel_import_id":null,
    "federation_subscription_number":null,
    "federation_subscription_number_only_numbers":null,
    "federation_subscription_type_id":null,
    "force_destroy":false,
    "guid":null,
    "id":59,
    "imported_from_sync":false,
    "modified_by_sync":false,
    "name":"ACME Corporation Inc.",
    "neighborhood":null,
    "note":null,
    "person_type":"JuridicalPerson",
    "phone":null,
    "site":null,
    "state":null,
    "supplier":true,
    "updated_at":"2011-04-16T16:15:16-03:00",
    "use_count":89,
    "zip_code":null
    "bank_account": {
      "account_digit":"1",
      "account_number":"12332",
      "agency_digit":"01",
      "agency_number":"2323",
      "bank_code":"001",
      "bank_name":"Banco do Brasil S.A."
    }
  }
}

Criar um cliente / fornecedor

POST /people

Cria um novo cliente / fornecedor com os parâmetros passados. Em caso de sucesso, retorna 201 Created, juntamente com a URI do cliente / fornecedor criado 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

JSON
XML

{
  "person":{
    "address":"Rua Tal",
    "address_number":"42",
    "city":"Rio de Janeiro",
    "complement":"sala 1234",
    "country":"Brasil",
    "customer":true,
    "email":"cliente@fulano.com",
    "federation_subscription_number":"27.206.831/0001-70",
    "name":"Fulano de Tal",
    "neighborhood":"Centro",
    "note":"Notas sobre este cliente...",
    "person_type":"JuridicalPerson",
    "phone":"(21) 5555-1234",
    "site":"http://www.fulano.com",
    "state":"RJ",
    "supplier":false,
    "zip_code":"22290-080"
    "bank_account_attributes": {
      "account_digit":"1",
      "account_number":"12332",
      "agency_digit":"01",
      "agency_number":"2323",
      "bank_code":"001",
      "bank_name":"Banco do Brasil S.A."
    }
  }
}

<person>
  <address>Rua Tal</address>
  <address_number>42</address_number>
  <city>Rio de Janeiro</city>
  <complement>sala 1234</complement>
  <country>Brasil</country>
  <customer type="boolean">true</customer>
  <email>contato@ciclano.com</email>
  <federation-subscription-number>478.400.634-62</federation-subscription-number>
  <name>Ciclano</name>
  <neighborhood>Centro</neighborhood>
  <note>Notas sobre este cliente...</note>
  <person-type>NaturalPerson</person-type>
  <phone>(21) 5555-1234</phone>
  <site>http://www.ciclano.com</site>
  <state>RJ</state>
  <supplier type="boolean">true</supplier>
  <zip-code>22290-080</zip-code>
  <bank-account-attributes>
    <account-digit>1</account-digit>
    <account-number>12332</account-number>
    <agency-digit>01</agency-digit>
    <agency-number>2323</agency-number>
    <bank-code>001</bank-code>
    <bank-name>Banco do Brasil S.A.</bank-name>
  </bank-account-attributes>
</person>

Exemplo de Resposta

JSON
XML

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/people/111
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT

{
  "person":{
    "account_id": 40,
    "address":"Rua Tal",
    "address_number":"42",
    "city":"Rio de Janeiro",
    "complement":"sala 1234",
    "country":"Brasil",
    "created_at":"2012-06-05T14:23:33-03:00",
    "customer":true,
    "email":"cliente@fulano.com",
    "excel_import_id":null,
    "federation_subscription_number":"27.206.831/0001-70",
    "federation_subscription_number_only_numbers":"27206831000170",
    "federation_subscription_type_id":null,
    "force_destroy":false,
    "id":111,
    "imported_from_sync":false,
    "modified_by_sync":false,
    "name":"Fulano de Tal",
    "neighborhood":"Centro",
    "note":"Notas sobre este cliente...",
    "person_type":"JuridicalPerson",
    "phone":"(21) 5555-1234",
    "site":"http://www.fulano.com",
    "state":"RJ",
    "supplier":false,
    "updated_at":"2012-06-05T14:23:33-03:00",
    "use_count":0,
    "zip_code":"22290-080"
    "bank_account": {
      "account_digit":"1",
      "account_number":"12332",
      "agency_digit":"01",
      "agency_number":"2323",
      "bank_code":"001",
      "bank_name":"Banco do Brasil S.A."
    }
  }
}

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/people/112
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <account-id type="integer">40</account-id>
  <address>Rua Tal</address>
  <address_number>42</address_number>
  <city>Rio de Janeiro</city>
  <complement>sala 1234</complement>
  <country>Brasil</country>
  <created-at type="dateTime">2012-06-05T14:56:18-03:00</created-at>
  <customer type="boolean">true</customer>
  <email>contato@ciclano.com</email>
  <excel-import-id type="integer" nil="true"></excel-import-id>
  <federation-subscription-number>478.400.634-62</federation-subscription-number>
  <federation-subscription-number-only-numbers>47840063462</federation-subscription-number-only-numbers>
  <federation-subscription-type-id type="integer" nil="true"></federation-subscription-type-id>
  <force-destroy type="boolean">false</force-destroy>
  <id type="integer">112</id>
  <imported-from-sync type="boolean">false</imported-from-sync>
  <modified-by-sync type="boolean">false</modified-by-sync>
  <name>Ciclano</name>
  <neighborhood>Centro</neighborhood>
  <note>Notas sobre este cliente...</note>
  <person-type>NaturalPerson</person-type>
  <phone>(21) 5555-1234</phone>
  <site>http://www.ciclano.com</site>
  <state>RJ</state>
  <supplier type="boolean">true</supplier>
  <updated-at type="dateTime">2012-06-05T14:56:18-03:00</updated-at>
  <use-count type="integer">0</use-count>
  <zip-code>22290-080</zip-code>
  <bank-account>
    <account-digit>1</account-digit>
    <account-number>12332</account-number>
    <agency-digit>01</agency-digit>
    <agency-number>2323</agency-number>
    <bank-code>001</bank-code>
    <bank-name>Banco do Brasil S.A.</bank-name>
  </bank-account>
</person>

Alterar um cliente / fornecedor

Exemplo de Requisição

PUT /people/:id

Altera o cliente / fornecedor especificado. 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 um cliente / fornecedor

Exemplo de Requisição

DELETE /people/:id

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

Clientes / Fornecedores (Person)

Listar clientes / fornecedores

Exemplo de Resposta

Exemplo de Busca Avançada

Exibir um cliente / fornecedor

Exemplo de Resposta

Criar um cliente / fornecedor

Exemplo de Requisição

Exemplo de Resposta

Alterar um cliente / fornecedor

Exemplo de Requisição

Apagar um cliente / fornecedor

Exemplo de Requisição

Clientes / Fornecedores (`Person`)