Buenas prácticas
El resto de la documentación está organizada por endpoint: cada página contesta "¿qué hace esto?". Útil cuando ya sabés qué llamar.
Esta sección contesta la otra pregunta, la primera: ¿en qué orden? Son los flujos completos, con las decisiones que vas a tener que tomar y lo que cuesta cada paso.
Acá no vas a encontrar campos, códigos de error ni payloads — eso vive en la página de cada endpoint y está linkeado donde corresponde. Si buscás "qué me devuelve", andá al endpoint; si buscás "qué llamo primero", quedate.
Los flujos
| Cuándo | ||
|---|---|---|
| Soy cliente de Mapaprop | una vez, al empezar | el arranque si automatizás tu propia cuenta: las cuatro cosas que funcionan distinto |
| Dar de alta un cliente | una vez por cliente | la ficha y la conexión con el portal |
| Publicar un aviso | cada propiedad | el caso base: cargar, verificar, publicar |
| Publicar un desarrollo | cada desarrollo | tiene un orden propio y conviene saberlo antes |
| Recibir consultas | continuo | las consultas que dejan las personas en los avisos |
| Preparate para el primer lead | una vez, cuando se enciende | lo que conviene tener listo el día que las consultas de la cuenta de tu cliente empiezan a llegarte solas |
| Dar de baja | cuando corresponda | bajar un aviso, desconectar una cuenta, borrar un cliente: son tres cosas distintas |
| Cuando algo no sale | — | por dónde empezar a mirar |
Las seis reglas que valen para todos
1 · Hay cosas que se hacen UNA VEZ y cosas que se hacen CADA VEZ
Es el error de diseño más caro de una integración, porque no falla: simplemente hace el triple de llamadas de las necesarias.
| Una vez por cliente | Cada vez |
|---|---|
| declarar su ficha | cargar o actualizar una propiedad |
| conectar su cuenta del portal | publicar, consultar el estado, dar de baja |
| mapear sus zonas (lo hacemos nosotros) | — |
2 · Lo que lee nuestro sistema es gratis; lo que le pregunta al portal se paga
El cupo de llamadas es de tu cliente, lo contrata él con el portal, y lo gasta tu integración. Cada portal lo define a su manera — el caso de Zonaprop está en Cupo mensual y límites.
| Gratis | Gasta una llamada del cupo |
|---|---|
| verificar un objeto | publicar y dar de baja |
| leer una propiedad o listarlas | preguntarle al portal el estado del aviso |
| leer la ficha del cliente y sus planes guardados | refrescar los planes contra el portal |
⚠️ Los errores también gastan. Un intento rechazado por el portal consume la llamada igual, así que conviene verificar antes — que es gratis.
3 · Guardá dos cosas de tu lado
- El
paIdque te devolvemos al crear una propiedad. Es con lo que la publicás, la consultás y la das de baja. Si lo perdés, tenés el listado y podés buscarla por tu propio código, pero es un paso que no hacía falta: el listado se recorre por páginas, y recorrerlo entero para encontrar una propiedad es trabajo que te ahorrás guardando elpaId. - Con qué
clientRefoperaste. Es cómo nos decís de qué cliente estás hablando, y lo elegís vos: usá el id que ya tenés en tu sistema.
4 · Reintentar es seguro, y no hace falta que lleves la cuenta
- Publicar de nuevo actualiza el aviso, no crea otro. Es la forma de reflejar un cambio de precio o de fotos.
- Dar de baja dos veces contesta bien las dos veces. No tenés que recordar si ya la bajaste.
- Lo que no es idempotente es crear: dos altas de la misma propiedad son dos propiedades. Mandá
tu propio código y usá el
paIdque te devolvemos.
5 · Mandá todos los datos, aunque un portal no use alguno
El objeto es el de Mapaprop, no el de un portal. Te pedimos todos los datos porque es lo que nos permite publicar en todos los portales posibles: cada uno acepta un subconjunto distinto, y el subconjunto cambia con el tipo de propiedad.
Cuando un portal no admite un campo que mandaste, no lo descartamos en silencio: te lo decimos en
omitted del verify, con el motivo y con qué pasa con el dato.
omitted es información, no una instrucción de sacar el campo. El dato queda guardado y viaja a
los portales que sí lo admitan. Si lo quitás de tu objeto para "limpiarlo", perdés esa
compatibilidad — y la vas a necesitar con el próximo portal.
6 · El listado se RECORRE, y lo que dice que terminaste no es que vino corto
Leer las propiedades de un cliente no es una llamada: es un recorrido por páginas. Mientras te devolvamos el puntero a la siguiente, quedan propiedades — aunque la página haya venido corta, o incluso vacía. Cortar el recorrido porque vino menos de lo que pediste te deja sin parte del inventario, y nada te avisa.
Es gratis (regla 2), así que recorrerlo entero no te cuesta cupo del portal: lo único que cuesta es hacerlo mal. La forma exacta está en el listado.
Los portales
Los métodos son los mismos para todos los portales: pasás el portal en la ruta y el resto no cambia. Lo que sí cambia por portal —cómo se conecta la cuenta, qué cupo tiene, qué planes— está en Publicación, y los flujos de acá apuntan ahí en vez de repetirlo.
Donde un portal se comporta distinto, lo decimos con su nombre puesto. Si leés una cifra o un nombre de plan sin portal al lado, es un error nuestro: escribinos.
Si tu app conecta un solo cliente
Los flujos están escritos para el caso general, donde tu app opera sobre varios clientes y nos decís con cuál en cada llamada. Si tu app está habilitada para uno solo, el cliente ya está fijado del lado nuestro y podés ignorar ese paso: todo lo demás es igual.