POST /properties/verify

Você envia o objeto de um imóvel e respondemos três coisas:

1. Se o objeto é válido de acordo com o contrato da Mapaprop, e o que falta se não for.
2. O que entendemos do que você enviou — quantos campos reconstruímos do seu array attributes.
3. Se cada portal poderia publicá-lo, e quando não, exatamente o que falta e de quem é o problema.

Para que serve

Integrar-se a vários portais tem um problema que aparece tarde: você envia um objeto que lhe parece completo, ele é publicado, e só então você vê que o anúncio saiu sem preço, sem piscina ou com o tipo errado — porque cada portal pede coisas diferentes e se cala sobre o que não entende.

Este endpoint deixa você ver isso antes de publicar, sem criar nada e sem precisar ter as contas dos portais conectadas.

Resource URL

https://property-api.mapaprop.com/property-v1/properties/verify

Autenticação

É exigido um token OAuth2 e o scope property-api-verify.

POST /property-v1/properties/verify
Host: property-api.mapaprop.com
Content-Type: application/json
Authorization: Bearer {access_token}

O token é obtido como qualquer outro: POST /api/action/oauth2-v1/authorize.

O corpo da requisição

{
  "canonical": { …el objeto de la propiedad… },
  "portals": ["argenprop", "zonaprop", "cabaprop"]
}

O objeto que vai em canonical é o de sempre: O objeto JSON do imóvel.

Se você enviar um portal que não existe, a requisição falha com um 400 em vez de ignorá-lo em silêncio.

Quais portais são reportados

A ideia é que não cheguem até você problemas de um portal que você não configurou. Se já declarou o Argenprop e mais nada, o Zonaprop não aparece na resposta nem conta no summary.

E se você ainda não configurou nenhum, vê todos: é o caso de quem está avaliando a integração e quer ver como o seu objeto se converte em cada portal antes de decidir.

publication — a configuração de publicação, dentro do objeto

Dentro de canonical você pode enviar uma chave publication com o que cada portal precisa da sua conta e das suas escolhas de publicação. Não é um campo do imóvel: é como você o publica.

{
  "publication": {
    "api": {
      "argenprop": { "advertiserId": 99999, "visible": true },
      "zonaprop": {
        "plan": { "plan": "SUPERDESTACADO" },
        "branch": { "custId": 1, "email": "contacto@ejemplo.com", "name": "Inmobiliaria", "phone1": "1144445555" }
      },
      "cabaprop": { "branchOfficeId": 42 }
    }
  }
}

Cada portal aceita também um token (string), que é validado na forma e nunca na validade: este endpoint não verifica contas. O seu valor não aparece em nenhuma parte da resposta.

publication não viaja aos portais como mais um campo: é consumido aqui e descartado.

A referência completa —os dois níveis, o que acontece se você enviar algo que não corresponde, e o detalhe do token— está na sua própria página: A chave publication.

A resposta

{
  "mode": "client",
  "object": {
    "valid": true,
    "contract": [],
    "mapapropZone": "1-2-189-973",
    "conflicts": [],
    "conflicts": []
  },
  "portals": {
    "argenprop": {
      "status": "fields_complete",
      "connection": "not_verified",
      "zone": {
        "sent": {
          "code": "1-2-189-973",
          "level": 3
        },
        "publishingTo": "Mar del Plata",
        "status": "mapped"
      },
      "blockers": [],
      "pendingAtPublishTime": []
    },
    "zonaprop": {
      "status": "fields_complete",
      "connection": "not_verified",
      "zone": {
        "sent": {
          "code": "1-2-189-973",
          "level": 3
        },
        "publishingTo": "General Pueyrredón",
        "status": "mapped"
      },
      "blockers": [],
      "pendingAtPublishTime": []
    },
    "cabaprop": {
      "status": "fields_complete",
      "connection": "not_verified",
      "zone": {
        "sent": {
          "code": "1-2-189-973",
          "level": 3
        },
        "status": "not_mapped",
        "message": "Todavía no tenemos mapeada esta zona para cabaprop. Escribinos con el código de zona y la publicamos: el mapeo queda hecho para siempre."
      },
      "blockers": [],
      "pendingAtPublishTime": []
    },
    "mercadolibre": {
      "status": "coming_soon",
      "message": "MercadoLibre: disponible pronto. La integración todavía no está habilitada en este endpoint."
    }
  },
  "summary": {
    "complete": 3,
    "of": 4
  }
}

object — o que aconteceu com o seu objeto

conflicts merece atenção: se você envia "type": 23 e o seu attributes diz "Departamento", é publicado como Departamento. Não é um erro, é a regra — mas se não era o que você queria, você vê aqui em vez de no anúncio.

portals — o que cada portal diz

Valores de status:

Cada blocker traz:

{ "field": "price",
  "kind": "missing",
  "message": "`price` es obligatorio en el objeto de Mapaprop y no vino…",
  "youCanFixIt": true }

youCanFixIt responde à única pergunta que importa sobre um blocker: eu resolvo isto enviando mais dados, ou é uma limitação do portal? Se for true, envie o dado. Se for false, esse portal não admite o que você está pedindo e não há JSON que resolva.

zone — em qual zona vamos publicar

Cada portal tem o seu próprio mapa de zonas, e nós mantemos a tradução entre a sua zona da Mapaprop e a desse portal. zone mostra as duas pontas:

{ "sent": { "code": "1-2-189-973", "level": 3 },
  "publishingTo": "Mar del Plata",
  "status": "mapped" }

Os estados:

summary

{ "summary": { "complete": 3, "of": 4 } }

Quantos portais têm os obrigatórios completos, sobre o total avaliado.

Os campos obrigatórios da Mapaprop prevalecem sobre os do portal

Esta é a coisa mais importante de entender sobre o endpoint.

A Mapaprop tem o seu próprio contrato de campos obrigatórios, e ele não depende do que cada portal pede. Se faltar um desses campos, nenhum portal fica em fields_complete — mesmo que esse portal em particular não o exija.

Exemplo: o Argenprop não exige o preço para montar o seu anúncio. Ainda assim, se você não enviar price:

{
  "object": {
    "valid": false,
    "contract": [ { "field": "price", "rule": "required", "detail": "" } ]
  },
  "portals": {
    "argenprop": {
      "status": "missing_data",
      "blockers": [
        { "field": "price",
          "kind": "missing",
          "message": "`price` es obligatorio en el objeto de Mapaprop y no vino. Sin él no se publica en ningún portal, lo exija o no este portal en particular.",
          "youCanFixIt": true }
      ]
    }
  },
  "summary": { "complete": 0, "of": 4 }
}

A lista completa de campos obrigatórios está em O objeto JSON do imóvel.

Não é preciso ter o portal conectado

O campo connection diz se a conta desse portal está conectada, mas não condiciona nada: o objeto é mapeado do mesmo jeito e os blockers são calculados do mesmo jeito.

É um dado ao lado, e continua importando: um objeto impecável não é publicado se a conta não estiver conectada. Mas para aperfeiçoar o seu objeto você não precisa ter nenhuma.

Erros

{ "error": "Portales desconocidos: idealista. Válidos: argenprop, zonaprop, cabaprop, mercadolibre, mapaprop" }

MercadoLibre

Sai sempre como coming_soon. A integração existe mas ainda não está habilitada neste endpoint, e preferimos não mostrar um mapeamento sem verificar: você o tomaria por bom.

Como usá-lo

1. Envie o seu objeto exatamente como você o tem hoje.
2. Olhe primeiro object.valid e object.contract. Se faltar um obrigatório, resolva isso — ele está bloqueando todos os portais ao mesmo tempo.
3. Olhe object.conflicts. Se aparecer algo, o seu attributes e os seus campos avulsos estão se contradizendo, e attributes ganha.
4. Portal por portal, resolva os blockers com youCanFixIt: true.
5. Os youCanFixIt: false você não resolve: são limites do portal.
6. Repita. Nada é criado, então teste quantas vezes precisar.