BETA

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 Mapapropuna vez, al empezarel arranque si automatizás tu propia cuenta: las cuatro cosas que funcionan distinto
Dar de alta un clienteuna vez por clientela ficha y la conexión con el portal
Publicar un avisocada propiedadel caso base: cargar, verificar, publicar
Publicar un desarrollocada desarrollotiene un orden propio y conviene saberlo antes
Recibir consultascontinuolas consultas que dejan las personas en los avisos
Preparate para el primer leaduna vez, cuando se enciendelo que conviene tener listo el día que las consultas de la cuenta de tu cliente empiezan a llegarte solas
Dar de bajacuando correspondabajar 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 clienteCada vez
declarar su fichacargar o actualizar una propiedad
conectar su cuenta del portalpublicar, 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.

GratisGasta una llamada del cupo
verificar un objetopublicar y dar de baja
leer una propiedad o listarlaspreguntarle al portal el estado del aviso
leer la ficha del cliente y sus planes guardadosrefrescar 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

  1. El paId que 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 el paId.
  2. Con qué clientRef operaste. 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 paId que 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.