Introdução à Express API

Construa seu próprio site ou app —que roda no seu próprio servidor, com o seu site e o seu design— usando a Express API do Mapaprop para servir o inventário da sua conta (imóveis, empreendimentos, filiais, zonas). É uma API para desenvolvedores: o site ou sistema é seu e você o consome de fora; o Mapaprop não o hospeda. Todos os métodos operam sobre a conta dona do token —seu inventário e sua configuração—: o escopo vem do access token, não é enviado como parâmetro. As consultas enviadas pelos seus visitantes entram no seu Inbox do Mapaprop.

1. Obtenha seu access token

A Express API funciona com o seu Token de API do Mapaprop (não com o registro de app OAuth2 de terceiros). Se você já é cliente Mapaprop Pro+ (ou superior), você ativa seu token com um clique a partir da sua conta —Configuração > API Token— e o usa como Authorization: Bearer {token}. O token não expira (a menos que você o regenere ou desative). Guia passo a passo: Express API Token.

2. Como seu site é resolvido

Quais precisam de um site e quais não

Apenas dez serviços precisam de um site: os que retornam conteúdo do site —settings, settings-v2, design, features, menus, pages, pages/{url}, pages/static/{pageId}, posts, posts/{url}—. Servem para montar seu site com conteúdo que você administra a partir do Mapaprop.

Todos os serviços de inventário funcionam sem site: são resolvidos unicamente com a conta dona do token. São properties, properties/{propertyHash}, developments, development/properties, branches, types, operations, zones, zones/suggestions e messages (o envio de consultas).

Como o site é escolhido

Para os dez serviços de conteúdo não é necessário que você envie qual: seu site fica vinculado ao seu Token de API a partir da sua conta do Mapaprop, e todos o usam automaticamente. Você o vincula —ou cria um— em Configurações > Token de API, no cartão Função Site.

O site é resolvido assim:

1. Seu token já tem um site vinculado → esse é usado. É o caso normal e você não precisa fazer nada.
2. Seu token não tem site vinculado e você tem um único site ativo → esse é usado.
3. Seu token não tem site vinculado e você tem mais de um site ativo → você precisa indicar qual com o parâmetro websiteId. Exemplo: GET /api/action/express-v1/settings-v2?websiteId=1234. Só é aceito um websiteId que seja um dos seus próprios sites ativos (é validado em relação à conta do seu token); qualquer outro é rejeitado.

Um site conta como ativo a partir do momento em que você o cria na sua conta. Não é necessário que tenha um domínio apontado nem conteúdo carregado.

Erros ao resolver o site

Diante de um erro, a resposta é um JSON com os campos error (um código estável, ideal para sua integração) e description (texto legível), com status HTTP 400:

{
  "error": "AMBIGUOUS_WEBSITE",
  "description": "El cliente tiene mas de un sitio activo. Especifique el parametro websiteId."
}

3. Fluxo básico

O que você monta com esta API é o seu site com o seu inventário. Tudo se resolve a partir do token: não é preciso enviar de qual conta se trata.

1 · Busque os catálogos, uma vez

types e operations devolvem os tipos e as operações que você tem em uso, não o catálogo inteiro do país. Com isso você monta os filtros da busca sem oferecer opções que não dariam nenhum resultado. zones faz o mesmo com as zonas onde você tem imóveis, e zones/suggestions resolve o autocompletar enquanto o visitante digita.

Mudam pouco: busque-os ao iniciar e armazene-os em cache.

2 · Liste e busque

properties é a listagem, com from e size para paginar.

3 · Exiba a ficha

properties/{propertyHash} traz o imóvel completo.

4 · Os empreendimentos

developments lista os seus empreendimentos. Cada um traz em developmentProperties os ids das suas unidades, e com esses ids você pede as unidades a development/properties.

Sobre os campos do empreendimento — os 10 que a imobiliária declara e o bloco developmentStats com os números derivados das unidades — veja a página de developments.

5 · Receba as consultas

messages envia a consulta do seu visitante, e ela entra no seu Inbox da Mapaprop como qualquer outra. Se o seu site também receber imóveis de potenciais vendedores, isso vai por seller-submissions — e é o único serviço de inventário que sim precisa de um site (veja acima).

6 · O conteúdo do site, se você o administrar a partir da Mapaprop

Apenas se usar a Mapaprop para o conteúdo além do inventário: settings-v2 (a configuração), design (cores e tipografia), features, menus, pages e posts.

Estes são os que precisam de um site resolvido — é o que a seção anterior explica. Se o seu conteúdo vive no seu CMS, você nunca os usará.

4. Explorar serviços

GET /api/action/express-v1/settings-v2

GET /api/action/express-v1/design

GET /api/action/express-v1/branches

GET /api/action/express-v1/menus

GET /api/action/express-v1/types

GET /api/action/express-v1/operations

GET /api/action/express-v1/pages

GET /api/action/express-v1/pages/{url}

GET /api/action/express-v1/pages/static/{pageId}

GET /api/action/express-v1/posts

GET /api/action/express-v1/posts/{url}

GET /api/action/express-v1/zones

GET /api/action/express-v1/zones/suggestions

GET /api/action/express-v1/properties

GET /api/action/express-v1/development/properties

GET /api/action/express-v1/developments

GET /api/action/express-v1/properties/{propertyHash}

POST /api/action/express-v1/messages

POST /api/action/express-v1/seller-submissions

GET /api/action/express-v1/features

GET /api/action/express-v1/settings descontinuado