Cadastrar um cliente
Isto se faz uma vez por cliente, e depois não se mexe mais. São dois passos e uma decisão.
1 · você declara a ficha dele POST /customers → você escolhe o clientRef dele
2 · você conecta a conta dele ← aqui está a bifurcação: depende do portal
3 · (opcional) você confere GET /customers gratuito
1 · A ficha
POST /customers com os dados da imobiliária.
O que você decide aqui é o clientRef, e é a decisão que vai usar mais: é como você nos diz de que
cliente está falando em cada chamada posterior. Quem o escolhe é você — use o id que esse
cliente já tem no seu sistema. Não o geramos de propósito, justamente para que você não tenha que
manter uma tabela de equivalências.
A ficha inclui os dados de contato que vão sair publicados no anúncio. Não é administrativo: é o que a pessoa que faz a consulta vê. Uma ficha sem telefone publica um anúncio sem telefone.
As filiais dele, uma única vez
Depende de o seu cliente ter conta do Mapaprop ou não. É a única bifurcação deste passo:
Se não tem — o caso da maioria. Você declara as filiais dele na ficha, em
branches, cada uma com uma referência que você escolhe
(branchRef). Depois cada imóvel diz com qual sai, enviando esse branchRef.
Se tem — as filiais dele já existem e ele as edita no Mapaprop. Leia
GET /branches e declare apenas o vínculo entre sua referência
e o id real dele:
{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }
Os dados de contato dessa filial saem do Mapaprop, não do que você declarar. Assim nunca ficam duas versões do mesmo telefone com uma das duas desatualizada.
Seu branchRef nunca muda, igual ao seu clientRef e ao seu paId. Se seu cliente passar a
ter conta do Mapaprop mais adiante, a filial dele ganha um id nosso ao lado da sua referência
— e seu código continua enviando a mesma palavra.
É o mesmo trabalho de mapeamento que as zonas, e pelo mesmo motivo: o nome não é suficiente para identificar uma filial.
Depois do cadastro, cada filial administra-se uma a uma — sem reenviar a lista completa:
| Você quer… | Você chama |
|---|---|
| editar uma | PUT /branches/{branchRef} |
| apagar uma | DELETE /branches/{branchRef} |
As duas portas funcionam igual para os dois casos acima: se o seu cliente não tem conta Mapaprop
escreve-se a ficha dele, e se tem, a escrita vai para o Mapaprop. A resposta diz-lhe qual das duas
aconteceu, em scope.
Adicionar uma filial é um PUT /customers; apagar uma NÃO. O PUT da ficha substituibranches[] pelo que envia, por isso uma filial que esquece no payload não é apagada por erro: para
a apagar tem de a nomear com o DELETE. É de propósito — apagar uma filial com conta Mapaprop move
as suas propriedades.
2 · Conectar a conta dele no portal — a bifurcação
Há duas formas e não é você quem escolhe: quem define é o portal.
| Com um link | Com a credencial | |
|---|---|---|
| Quem autoriza | o seu cliente, abrindo um link | você, com a credencial que já conseguiu |
| Você administra uma credencial dele | não | sim |
| O que você nos manda | nada: pede o link e o repassa | a credencial da conta dele |
| Portais | Zonaprop · Argenprop | Argenprop · Cabaprop · MercadoLibre |
O Argenprop aceita as duas, e o enlace é o caminho recomendado: a credencial de integração dele é entregue pelo portal por e-mail à imobiliária, portanto com o enlace o seu cliente a escreve na nossa página e você não a manuseia.
Por que existem as duas: alguns portais não emitem nenhuma credencial por conta — a imobiliária entra, aceita, e a autorização fica do lado deles. Nesses não há nada que você possa guardar, e por isso o caminho é o link.
⚠️ Não são intercambiáveis. Se você tentar registrar uma credencial num portal que vai por link, dizemos isso com o nome do portal e com o link para pedi-lo. Não é um erro seu de permissões: é o caminho errado para esse portal.
A tabela completa de qual portal vai por onde está em Publicação.
3 · Verificar que ficou pronto (gratuito)
GET /customers devolve a ficha e, ao lado, o estado das
conexões dele. Não custa nada, então é a forma barata de confirmar antes de começar a publicar.
Nos portais que têm planos de publicação, aqui também vêm os planos do seu cliente — e isso é gratuito porque os trazemos na mesma chamada com a qual verificamos que ele autorizou. Não é preciso pedi-los à parte.
O que NÃO fazer no cadastro
- Gerar um
clientRefnosso. Quem o escolhe é você; use o seu. - Pedir os planos ao portal. Você já os tem a partir do passo 3, gratuitos e com a data.
- Mapear as zonas dele. Nós as resolvemos; você manda a sua.
- Esperar ter a conta conectada para começar a integrar. O verificador funciona igual sem conexão, então você pode deixar o seu mapeamento do objeto pronto antes de o seu cliente autorizar.
Se o seu aplicativo conecta um único cliente
O clientRef já está fixado do nosso lado: a ficha é uma e não é preciso nos dizer qual em cada
chamada. Os dois passos são os mesmos.
Relacionado
- Publicar um anúncio — o passo seguinte
- Clientes — os quatro métodos da ficha, incluindo atualizá-la quando mudar um dado de contato
- Filiais — os três métodos: consultá-las, editar uma e apagar uma
- Zonaprop · Argenprop — as seções dos dois portais que vão por link, cada uma com o que é próprio dele
- Consultar e desconectar — e dar baixa, para a diferença entre desconectar e apagar