Guia rápido de utilização


Como integrar à API

A API Vista Software & Internet é uma aplicação RESTful. Toda a comunicação utiliza dados no formato JSON, tanto para request quanto para response.

É necessário informar o cabeçalho "Accept: application/json" nas requisições, sem exceção!
A API tem os recursos orientados pela URL e utiliza os Status Codes para indicar os erros.

Certifique-se que a sua URL não contenha espaços em branco. Para isso, codifique suas pesquisas. Exemplo: urlencode("Porto Alegre"), ou Porto+Alegre.

Você pode utilizar o API List e Teste (Sandbox) no menu à esquerda para testar as requisições.

URL's da API:

Cada cliente terá sua url para integração com a API. Você deve solicitar a suporte@vistasoft.com.br

Ex: http://urldocliente.vistahost.com.br/

Caso você ainda não possua uma url, utilize (para testes):

http://sandbox-rest.vistahost.com.br/

Exemplo:


$key         =  'c9fdd79584fb8d369a6a579af1a8f681';
$url         =  'http://sandbox-rest.vistahost.com.br/reloadcache?key=' . $key;

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );

E os métodos que posso utilizar?
E a URI dos métodos?


Acesse a API List e Teste (Sandbox) para ver a lista completa de métodos e também efetuar testes de requisição na hora! Se você não possui chave, solicite à nossa equipe através do e-mail desenvolvimento@vistasoft.com.br

Você pode utilizar nossa chave de teste se precisar iniciar sua integração até receber sua chave.

Você pode informar seus dados e filtros no parâmetro pesquisa em formato JSON, conforme mostrado
no exemplo ao lado.

Chave de teste

c9fdd79584fb8d369a6a579af1a8f681

Exemplo:

$dados = array(
    'fields' => array( 'Cidade', 'Bairro', 'ValorVenda' )
);

$key         =  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; //Informe sua chave aqui
$postFields  =  json_encode( $dados );
$url         =  'http://sandbox-rest.vistahost.com.br/imoveis/listar?key=' . $key;
$url        .=  '&pesquisa=' . $postFields;

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );

Mas quais parâmetros posso utilizar em "pesquisa"?


fields

O parâmetro "fields" é um array em formato JSON. Nele, você especifica quais campos você vai utilizar.
Atenção: Caso você não informe os campos que quer utilizar, apenas a API retornará apenas o código.
Todos os demais campos que você vai utilizar devem ser informados neste parâmetro.

&pesquisa={"fields":["Bairro", "Cidade", "ValorVenda"]}

Exemplo:

Dados do imóvel cujo código é 2560 com suas informações relacionadas:
$dados = array(
    'fields'    =>
            array(
                'Codigo', 'Cidade', 'Bairro', 'ValorVenda', 'Dormitorio',
                'Vagas', 'Churrasqueira', 'Lareira', 'Descricao', 'FotoDestaque',

                array('fotos'   =>
                        array(
                              'Foto', 'FotoPequena', 'Destaque','Tipo', 'Descricao'
                              )
                      ),

                array('Corretor' =>
                        array(
                              'Nome', 'Fone', 'E-mail', 'Creci'
                              )
                      ),

                array('Agencia' =>
                        array(
                              'Nome', 'Fone', 'Endereco', 'Numero',
                              'Complemento', 'Bairro', 'Cidade'
                             )
                      )
                )
);

$key         =  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; //Informe sua chave aqui
$postFields  =  json_encode( $dados );
$url         =  'http://sandbox-rest.vistahost.com.br/imoveis/detalhes?key=' . $key;
$url        .=  '&pesquisa=' . $postFields;

$url        .=  '&imovel=2560';

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );

filter

Vamos filtrar as informações que precisamos. O parâmetro "filter" é um objeto em formato JSON.

- Para campos de texto, Você pode informar um único texto ou array para pesquisar por vários conteúdos.
&pesquisa={"filter":{"Bairro":"Centro","Cidade":"São+Paulo"}}

&pesquisa={"filter":{"Bairro":["Centro","Moema","Jardim+Bela+Vista"],"Cidade":"São+Paulo"}}


- Para campos de valores e datas, você pode especificar um valor específico ou um intervalo.
(de 250 mil a 500 mil)
&pesquisa={"filter":{"ValorVenda":[250000, 500000]}

(de 01/10/2014 a 30/10/2014 mil)
&pesquisa={"filter":{"DataAtualizacao":["2014-10-01", "2014-10-30"]}

Outras necessidades de filtros

Você pode especificar um array onde o primeiro valor é um dos símbolos abaixo:
  • ">" - Maior que x
  • "<" - Menor que x
  • ">=" - Maior ou igual à x
  • "<=" - Menor ou igual à x
  • "like" - Similar ao texto
  • "!=" - Diferente de x
&pesquisa={"filter":{"ValorVenda":[">=", 500000]}

Exemplo:

Pesquisa utilizando filter:
$dados = array(
    'fields'    =>
            array(
                'Codigo', 'Cidade', 'Bairro', 'ValorVenda', 'Dormitorio',
                'Vagas', 'Churrasqueira', 'Lareira',

            array('Agencia' =>
                    array(
                          'Nome', 'Fone', 'Endereco', 'Numero',
                          'Complemento', 'Bairro', 'Cidade'
                          )
                  )

            ),
    'filter'    => array(
                        array('Bairro'  => array('Centro', 'Moema')),
                        'Cidade'        => 'São+Paulo'
                    )
);

$key         =  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; //Informe sua chave aqui
$postFields  =  json_encode( $dados );
$url         =  'http://sandbox-rest.vistahost.com.br/imoveis/listar?key=' . $key;
$url        .=  '&pesquisa=' . $postFields;

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );

paginacao

Os resultados da API são SEMPRE paginados. Por padrão O MÁXIMO DE RESULTADOS É 50, ou seja, é necessário informar a página e o número de resultados por página desejado.
Como os resultados são sempre paginados, você vai precisar saber quantas páginas existem no TOTAL e quantos registros há por página. Para obter os TOTAIS e PÁGINAS, informe um GET na sua URL "showtotal=1"
&pesquisa={"paginacao":{"pagina":1,"quantidade":10}&showtotal=1

Os totais devem retornar no final do JSON com uma estrutura conforme o exemplo abaixo:
 {
  "total": 460,
  "paginas": 46,
  "pagina": 1,
  "quantidade": 10
  }

Exemplo:

Pesquisa utilizando paginação:
$dados = array(
    'fields'    =>
            array(
                'Codigo', 'Cidade', 'Bairro', 'ValorVenda', 'Dormitorio',
                'Vagas', 'Churrasqueira', 'Lareira',

            array('Agencia' =>
                    array(
                          'Nome', 'Fone', 'Endereco', 'Numero',
                          'Complemento', 'Bairro', 'Cidade'
                          )
                  )

            ),
    'filter'    => array(
                        array('Bairro'  => array('Centro', 'Moema')),
                        'Cidade'        => 'São+Paulo'
                    ),
    'Order'     => array(
                     array('Bairro'      => 'asc',
                           'ValorVenda'  => 'asc'
                     )
                    ),
    'paginacao' => array(
                    'pagina'        => 1,
                    'quantidade'    => 20
                    )
);

$key         =  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; //Informe sua chave aqui
$postFields  =  json_encode( $dados );
$url         =  'http://sandbox-rest.vistahost.com.br/imoveis/listar?key=' . $key;
$url        .=  '&pesquisa=' . $postFields;

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );

order

Ordenar os resultados é sempre bom. Utilize um objeto json com os campos que deseja ordenar, informando a direção asc (ascendente) ou desc (descendente) .
&pesquisa={"order":{"ValorVenda":"asc","Bairro":"asc"}

Exemplo:

Pesquisa utilizando order:
$dados = array(
    'fields'    =>
            array(
                'Codigo', 'Cidade', 'Bairro', 'ValorVenda', 'Dormitorio',
                'Vagas', 'Churrasqueira', 'Lareira',

            array('Agencia' =>
                    array(
                          'Nome', 'Fone', 'Endereco', 'Numero',
                          'Complemento', 'Bairro', 'Cidade'
                          )
                  )

            ),
    'filter'    => array(
                        array('Bairro'  => array('Centro', 'Moema')),
                        'Cidade'        => 'São+Paulo'
                    ),
    'Order'     => array(
                     array('Bairro'      => 'asc',
                           'ValorVenda'  => 'asc'
                     )
                    )
);

$key         =  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; //Informe sua chave aqui
$postFields  =  json_encode( $dados );
$url         =  'http://sandbox-rest.vistahost.com.br/imoveis/listar?key=' . $key;
$url        .=  '&pesquisa=' . $postFields;

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );

advFilter

Tente manter suas consultas simples. Em outras palavras, EVITE usar o advFilter. Mas, como nem tudo é um mar de rosas, às vezes precisamos de um filtro muito específico.

Como Funciona?
O advFilter utiliza a mesma forma de pesquisa que o parâmetro filter, porém, permite especificar grupos com And e Or para buscas bem detalhadas.

Mostrando na prática
                        {"advFilter":{
                            "Bairro":["Centro","Moema"],
                            "Or":{
                                "ValorVenda":[250000, 500000],
                                "And":{
                                    "Cidade":"São+Paulo",
                                    "Finalidade":"Venda"
                                }
                            }
                        }
                    

E agora? Que coisa é essa?
Toda vez que você utiliza objeto "Or", a API entende que todos os itens nele são tratados como OU.
Toda vez que você utiliza objeto "And", a API entende que todos os itens nele são tratados como E.

O exemplo acima é o mesmo que uma QUERY da seguinte forma:
                        WHERE (
                        Bairro in ("Centro","Moema") AND
                        ((ValorVenda BETWEEN 250000 AND 500000)
                            OR (Cidade = "São+Paulo" AND Finalidade = "Venda")
                            )
                        )
                    

Exemplo:

Pesquisa utilizando advFilter:
$dados = array(
 'fields' =>
   array(
     'Codigo', 'Cidade', 'Bairro', 'ValorVenda', 'Dormitorio','Vagas', 'Churrasqueira', 'Lareira',
      array( 'Agencia' => array('Nome', 'Fone', 'Endereco', 'Numero','Complemento', 'Bairro', 'Cidade') )
   ),
 'advFilter' =>
   array(
    "Or" => array('Bairro' => array( 'Centro', 'Moema' ) ),
            array('ValorVenda' => array( 250000, 500000 ) )
    ),
 'Order' =>
   array(
     'Bairro' => 'asc',
     'ValorVenda'  => 'asc'
    ),
 'paginacao' =>
   array(
    'pagina' => 1,
    'quantidade' => 20
   )
);

$key         =  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; //Informe sua chave aqui
$postFields  =  json_encode( $dados );
$url         =  'http://sandbox-rest.vistahost.com.br/imoveis/listar?key=' . $key;
$url        .=  '&pesquisa=' . $postFields;

$ch = curl_init($url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER , array( 'Accept: application/json' ) );
$result = curl_exec( $ch );

$result = json_decode( $result, true );
print_r( $result );