logo
API docs by Redocly

Integração DWV (1.1.0)

E-mail: suporte@dwvapp.com.br

Introdução

Esta documentação descreve o funcionamento da API que a DWV desenvolveu para os integradores externos. Através da nossa API, os sistemas externos podem interagir com a nossa base de imóveis e demais informações disponibilizadas pela DWV.

O atual uso da API é para integração de sites e de sistemas imobiliários (CRMs), e o escopo do uso deve sempre respeitar os termos do contrato estabelecidos entre a DWV e a sua empresa.

Estrutura DWV

Nesta seção será explanado sobre a estrutura que a DWV utiliza para organizar os imóveis que se encontram em seu banco. É altamente recomendado ler essa seção, para que se possa utilizar a API sem complicações.

Propriedades

As propriedades se referem a unidades, terceiros e imóveis de parceria que as imobiliárias realizaram a seleção para a integração no seu site ou sistema imobiliário (CRMs).

Lançamentos

Produto da construtora(empreendimento).

Unidades

Frações de um lançamento(Apartamentos,Terrenos,Salas comerciais entre outros), possuem informações do empreendimento e próprias como metragens, valor e condições de pagamento.

Terceiros

Imóveis usados que entraram como forma de pagamento para a construtora, também conhecidos como dação.

Imóveis de parceria (Clube Premium)

Imóveis exclusivos que pertencem a outra imobiliária da rede DWV (Clube Premium), e que a imobiliária integradora selecionou para publicar no seu site ou sistema imobiliário (CRMs).

Os imóveis de parceria são entregues nas mesmas rotas e no mesmo formato dos terceiros, dentro do objeto third_party_property. O campo que distingue os dois é o property_type:

  • third_part_property: terceiro de construtora (dação)
  • third_part_property_agency: imóvel de parceria de outra imobiliária da rede DWV

Cada item continua tendo os objetos unit, building, third_party_property e construction_company. O que identifica o tipo do imóvel é quais deles vêm preenchidos:

Tipo unit building third_party_property construction_company
Unidade de lançamento preenchido preenchido null preenchida
Terceiro (dação de construtora) null null preenchido, com property_type: "third_part_property" preenchida
Imóvel de parceria (Clube Premium) null null preenchido, com property_type: "third_part_property_agency" com todos os campos nulos

Nos imóveis de parceria o objeto construction_company é retornado com todos os campos nulos, e a API não expõe a imobiliária proprietária do exclusivo, sendo o anúncio da imobiliária que realizou a integração.

O recebimento de imóveis de parceria é habilitado por sistema integrador. Enquanto a DWV não habilitar o seu sistema, as imobiliárias não conseguem selecionar imóveis de parceria para o mesmo e a listagem nunca conterá esse tipo de imóvel. Para solicitar a habilitação, entre em contato pelo e-mail suporte@dwvapp.com.br.

O campo property_type é retornado por padrão na listagem e no detalhe, mas ainda não é aceito no parâmetro fields: pedir property_type nesse filtro faz a requisição responder 400 com a mensagem some field in the fields filter is invalid, e o campo também não aparece na lista de campos disponíveis. Para receber o property_type, consulte a listagem ou o detalhe sem o parâmetro fields.

O construction_stage é derivado das datas de andamento da obra do cadastro do imóvel. Como os exclusivos de parceria normalmente não têm essas datas, o valor entregue é Usado — que é justamente o valor recusado pelos filtros property_condition e construction_stage para imóveis de parceria (veja o aviso em cada um desses filtros na rota de listagem).

Quartos e Suítes

No sistema DWV, o número total de quartos inclui também as suítes. Ou seja, não há separação entre "quartos" e "suítes" no total de dormitórios. Para fins de distinção:

  • Número de quartos sem suíte = Total de quartos cadastrados - Número de suítes

Banheiros

A contagem de banheiros é tratada da mesma forma como os quartos e suítes.

  • Número de banheiros sociais = Banheiros sociais(fora da suíte) - Banheiros da suíte

Authentication

Todas as rotas dessa API se utilizam da autenticação via header sendo que esse tipo de autenticação necessitam de um token. Estes token são fornecidos pelas imobiliarias, onde para as mesmas conseguirem esse token, devem acessar o sistema de Integração DWV e gerar o token para o sistema de integração desejado.

Para os que ainda não estão familiarizados com este tipo de autenticação, você deve inserir no header de sua requisição um parametro chamado token com o seu valor TOKEN_IMOBILIARIA. Um exemplo de como ficaria uma requisição pode ser visualizada abaixo.

curl -H "token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbW9iaWxpYXJpYV9pZCI6IjEiLCJpbnRlZ3JhdGlvbl9pZCI6MSwiaWF0IjoxNjA3MzY3ODA2fQ.YFqnvt0Xg7MopUS-PpZYO53HF54ru6G22RshZiGjr_E" \
"https://apisandbox.dwvapp.com.br/integration/properties"

Rate Limit

As rotas dessa API possuem o limite de 100 requests por minuto, caso este limite seja excedido, as requisições subsequentes no período de 60 segundos irão retornar status code 429.

Propriedades

Propriedades

Listar Propriedades

Lista todas as propriedades selecionadas para integração de uma imobiliaria em especifico, sendo esta definida pelo token de autenticação utilizado no header. Para aperfeiçoar os tipos de imóveis que deseja exibir, tem-se a possibilidade de aplicar alguns filtros."

Authorizations:
realEstateAgencyAuth
query Parameters
limit
integer
Default: 20

Define o máximo de propriedades que serão exibidos em cada página

page
integer
Default: 1

Seleciona a pagina para listar os items.

search
string
Example: search=Propriedade 1

Traz propriedades onde algum dos campos foi encontrado no text search. Você pode pesquisar por propriedades também baseado por informações da construtora e empreendimento.

address
string
Example: address=Rua 248, 322

Filtrar imóveis por endereço informado

city
string
Example: city=Itapema

Filtrar imóveis por uma cidade em especifíco

state
string
Example: state=SC

Filtrar imóveis por um estado em especifíco

bedrooms
string
Example: bedrooms=1,3+

Filtrar imóveis pela quantidade de quartos informado. Pode-se passar mais de um valor nesta query, sendo que os mesmos tem que estar separados entre ",".

Esta query permite utilizar o operador +, sendo que este operador pode ser traduzido como >=.

unit_suites
string
Example: unit_suites=1,3+

Filtrar imóveis pela quantidade de suites informado. Pode-se passar mais de um valor nesta query, sendo que os mesmos tem que estar separados entre ",".

Esta query permite utilizar o operador +, sendo que este operador pode ser traduzido como >=.

unit_parking_spaces
string
Example: unit_parking_spaces=1,3+

Filtrar imóveis pela quantidade de vagas de garagem disponíveis no mesmo. Pode-se passar mais de um valor nesta query, sendo que os mesmos tem que estar separados entre ",".

Esta query permite utilizar o operador +, sendo que este operador pode ser traduzido como >=.

property_condition
string
Enum: "new" "used"

Filtrar imóveis por condiçöes em que os mesmos se encontram.

Atenção: este filtro não retorna imóveis de parceria (Clube Premium), pois contempla apenas unidades e terceiros de construtora. Caso precise dos imóveis de parceria, não o utilize.

types
string
Enum: "apartment" "comercialRoom" "garden" "penthouse" "differentiated" "showroom" "decorated" "roof" "furnished" "duplex" "smallFarm" "house" "hotel" "land" "warehouse"

Filtrar imóveis por um tipo específico.

last_updates
string
Example: last_updates=2020-10-25,2020-10-28

Filtrar imóveis por um range de data definido. Sendo que estas datas devem estar no seguinte formato: 22/10/2020

status
string
Enum: "active" "inactive" "auto_inactive"

Filtrar imóveis selecionados pela imobiliária através do status em que se encontram para serem integrados Obs: (auto_inactive é um status que o próprio sistema define quando o imóvel se encontra vendido ou inativado)

deleted
string
Enum: true false

Filtrar imóveis que haviam sido selecionados pela imobiliária anteriormente, mas a mesma acabou deletando para que assim não fosse integrado no sistema.

construction_stage_raw
string
Enum: "pre-market" "under construction" "new" "used"

Indica o estágio de construção da propriedade.

construction_stage
string
Enum: "Pré-lançamento" "Em construção" "Lançamento" "Usado"

Indica o estágio de construção da propriedade.

Atenção: quando filtrado por Usado, os imóveis de parceria (Clube Premium) não são retornados, pois esse valor contempla apenas os terceiros de construtora.

incorporation
string
Example: incorporation=r32

registro de incorporação ou equivalente dos empreendimentos

rent
string
Enum: true false

Informa quando o imóvel é aluguel.

fields
json
Example: fields=["id","title", {"building": ["title", {"gallery": ["url"]}]}]

filtra campos específicos no payload. Os campos podem ser especificados como strings simples ou objetos aninhados. Os objetos aninhados devem ser específicados como um objeto JSON com as chaves sendo os nomes dos objetos e os valores sendo uma lista de campos para retornar.

Obs: Ao chamar objetos aninhados é obrigatório selecionar pelo menos um campo filho do objeto, então algo como fields=["building"] ira retornar um erro, enquanto que fields=[{"building":["title"]}] ira funcionar.

Atenção: O campo property_type do objeto third_party_property ainda não é aceito nesse filtro. Pedi-lo faz a requisição responder 400 com a mensagem some field in the fields filter is invalid. Para receber o property_type e identificar os imóveis de parceria (Clube Premium), consulte a rota sem o parâmetro fields.

Responses

Response samples

Content type
application/json
Example
{}

Exibir detalhes de uma propriedade

Exibe todos os detalhes de um propriedade

Authorizations:
realEstateAgencyAuth
path Parameters
propertyId
required
integer

ID da propriedade que você quer obter mais detalhes

Responses

Response samples

Content type
application/json
Example
{}

Condições das Propriedades

Lista todas as condições de imóveis existentes que podem ser utilizados no filtro property_condition que se encontra na rota que busca as propriedades selecionadas para integração de uma certa imobiliaria

Authorizations:
realEstateAgencyAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Tipos de Propriedades

Lista todos os tipos existentes de imóveis, os quais podem ser utilizados no filtro types na rota que busca as propriedades selecionadas por uma imobiliaria para integração

Authorizations:
realEstateAgencyAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Cidades e Bairros Integrados

Lista todas as cidades e bairros que a imobiliária possui imóveis integrados.

Authorizations:
realEstateAgencyAuth
query Parameters
limit
integer
Default: 20

Define o máximo de items que serão exibidos em cada página

page
integer
Default: 1

Seleciona a pagina para listar os items.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "perPage": 20,
  • "page": 1,
  • "lastPage": 1,
  • "data": [
    ]
}

Campos disponíveis

Lista os campos disponíveis para o parametro fields.

Authorizations:
realEstateAgencyAuth

Responses

Response samples

Content type
application/json
[
  • "id",
  • "title",
  • "status",
  • "..."
]

Propriedade

id
integer

ID de integração do imóvel

title
string

Título de anúncio do imóvel

description
string

Descrição do imóvel para utilizar no anúncio

advertisement_title
string
Deprecated

Título de anúncio do imóvel

advertisement_description
string
Deprecated

Descrição do imóvel para utilizar no anúncio

status
string
Enum: "active" "inactive" "auto_inactive"

Informa o estado de integração do imóvel (A imobiliaria pode ativar ou desativar a integração do imóvel, mas quando o status for auto_inactive significa que o imóvel no momento não se encontra disponivel para venda no sistema e por isso deve-se ignorar integração deste imóvel)

construction_stage
string
Enum: "Pré-lançamento" "Em construção" "Lançamento" "Usado"
construction_stage_raw
string
Enum: "pre-market" "under construction" "new" "used"

Estágio da obra

incorporation
string or null

Registro de incorporação do empreendimento (retornado apenas para unidades de lançamento - em terceiros e em imóveis de parceria vem sempre null)

rent
string
Enum: true false

Informa quando o imóvel é aluguel.

deleted
boolean

Informa se o imóvel integrado pela imobiliária, foi deletada pela mesma da integração.

address_display_type
string or null

Tipo de exibição que a imobiliária escolheu para exibir os endereços das propriedades (vem null enquanto a imobiliária não configurar a exibição do endereço do anúncio, e nesse caso deve-se assumir a exibição padrão do seu sistema)

object or null

Informações da unidade selecionada para integração

object or null

Informações do empreendimento

object or null

Informações do terceiro ou do imóvel de parceria selecionado para integração (o campo property_type identifica qual dos dois)

object

Informações da Construtora (nos imóveis de parceria este objeto é retornado com todos os campos nulos, pois não há construtora envolvida)

last_updated_at
string

Data da última atualização

{
  • "id": 0,
  • "title": "string",
  • "description": "string",
  • "advertisement_title": "string",
  • "advertisement_description": "string",
  • "status": "active",
  • "construction_stage": "Pré-lançamento",
  • "construction_stage_raw": "pre-market",
  • "incorporation": "string",
  • "rent": true,
  • "deleted": true,
  • "address_display_type": "string",
  • "unit": {
    },
  • "building": {
    },
  • "third_party_property": {
    },
  • "construction_company": {
    },
  • "last_updated_at": "string"
}