Documentação API Rest

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 através de um chamado na Central de Serviços do Novo Vista.

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 da Central de Serviços do Novo Vista.

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)

&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 );

Guia rápido de utilização

Como integrar à API

URL's da API:

Exemplo:

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

Chave de teste

Exemplo:

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

fields

Exemplo:

filter

Outras necessidades de filtros

Exemplo:

paginacao

Exemplo:

order

Exemplo:

advFilter

Exemplo:

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