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, sua configuração, seus leads—: 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

TBD

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