BETA

Publicar un aviso

El caso base: una propiedad, un portal. Asumimos que el cliente ya tiene su ficha y su cuenta del portal conectada — si no, empezá por dar de alta un cliente, que se hace una sola vez.

El camino

1 · cargar la propiedad        POST   /properties              → te devuelve el paId
2 · verificar                  POST   /properties/verify       gratis, y conviene
3 · publicar                   PUT    …/publication/{portal}
4 · ¿cómo quedó?               GET    /properties/{paId}       gratis  ·  o al portal (cuesta)
5 · actualizar                 PUT    …/publication/{portal}   el MISMO llamado del paso 3
6 · pagar por posición         GET    …/publication/{portal}/positioning   según el portal
7 · dar de baja                DELETE …/publication/{portal}

Los pasos 1 y 3 son los obligatorios. El 2 es gratis y te ahorra llamadas; del 4 al 7, según lo que necesites.

1 · Cargar la propiedad

Antes de la primera vez conviene leer dos cosas: el modelo de propiedad —por qué las claves son las mismas en todos los países— y el objeto JSON, que es el contrato de los campos.

POST /properties con tu objeto. Te devolvemos un paId: guardalo, es con lo que vas a hacer todo lo demás.

Mandá tu propio código en el objeto. Es tu ancla: si perdés el paId, lo recuperás del listado buscando por él — el listado se recorre por páginas, así que para una cartera grande es más barato guardar el paId que buscarlo.

Las fotos y los planos viajan dentro del mismo objeto, no en llamadas aparte. Una sola llamada con todo. Las descargamos nosotros, así que la respuesta puede decir que todavía están en proceso — eso es normal y no bloquea publicar. Si alguna no se pudo bajar, el bloque images lo dice y se reintenta sin tener que mandar el objeto de nuevo.

Si sos cliente de Mapaprop y generaste tu token desde la app, este mismo paso hace algo más: la propiedad entra sola a tu cuenta de Mapaprop cuando terminan de procesarse las fotos, sin que pidas nada. Queda cargada, no publicada — publicarla sigue siendo el paso 3. El estado del alta viaja en el bloque mapaprop y está explicado en Mapaprop.

Y tu propia cuenta es uno de los destinos del paso 3: se publica con mapapropapi en la misma ruta, no gasta cupo de ningún portal, y también publica en las redes donde estés. El paso 2 no aplica: verificar es contra los portales.

2 · Verificar (gratis, y es la mejor inversión del flujo)

POST /properties/verify te dice, portal por portal, si ese aviso saldría — y qué falta si no. No le pregunta nada al portal, así que no gasta cupo ni depende de que el portal esté arriba.

Por qué conviene: un intento rechazado por el portal gasta la llamada igual. Verificar primero es gratis, así que el cálculo es fácil.

Te separa dos cosas, y la distinción importa:

  • Lo que falta en el objeto → lo arreglás vos, en lo que mandás.
  • Lo que falta de la cuenta (el plan, la sucursal) → sale de la conexión del cliente, no de la propiedad. No hace falta que lo mandes en la verificación.

Y chequea los dos catálogos: la zona, con su jerarquía, y los atributos contra el catálogo del país de la propiedad. Son los errores que más caro salen descubrir tarde, porque ninguno de los dos rebota: la propiedad entra igual, y después no aparece en las búsquedas por ubicación o le falta una característica. Mirando la propiedad no se nota — por eso conviene este paso.

Usalo también antes de tener la cuenta conectada. El verificador funciona igual y te dice si tu mapeo del objeto está bien, así podés tener tu integración lista antes de que tu cliente autorice.

3 · Publicar

PUT …/publication/{portal}.

La única decisión del paso: en los portales que tienen planes de publicación, elegís con cuál publicar. Lo podés mandar en la llamada o dejarlo guardado en la configuración de la propiedad — y si mandás los dos, gana el de la llamada, para que puedas cambiar de plan sin reescribir la propiedad.

Si el plan que pediste no está disponible, la respuesta te dice cuáles sí tiene tu cliente. No hace falta consultarlo antes.

La otra decisión, y es opcional: con qué datos de contacto sale este aviso. Por defecto usa los de la ficha de tu cliente; si querés otros —el asesor que lleva esa propiedad, su teléfono— los mandás en la misma llamada. El correo del asesor tiene que ser el de un usuario que exista en la cuenta del portal, y de ahí sale el padrón de tu cliente, que en su nivel básico no gasta cupo. ⚠️ Si mandás uno que el portal no reconoce, no te da error: lo reemplaza por el del administrador y publica igual.

Y si la propiedad está reservada, vendida o alquilada, el aviso lo refleja solo: el estado viaja en el objeto y se aplica en este mismo paso — ver el estado de la propiedad en el portal. No hay nada más que llamar. ⚠️ Pero una propiedad tiene UN estado o ninguno: dos prendidos se rechazan en el paso 2.

4 · Ver cómo quedó — y acá hay dos caminos que no son lo mismo

Qué te diceCuesta
GET /properties/{paId}lo que nosotros registramos de esa publicacióngratis
GET …/publication/{portal}lo que dice el portal: si está online, su URL, las visitas1 llamada

Leé primero el gratis. Al portal preguntale cuando necesites algo que sólo él sabe —la URL del aviso, las visitas— o cuando sospeches que alguien lo cambió del lado del portal.

⚠️ No consultes el estado en un loop. Con 400 propiedades son 400 llamadas del cupo de tu cliente.

5 · Actualizar

No hay un endpoint de actualizar la publicación: es el mismo PUT del paso 3. Volver a llamarlo actualiza el aviso en vez de duplicarlo.

Así que el flujo de un cambio de precio es: actualizás la propiedad → publicás de nuevo. Dos llamadas, y la segunda es la que llega al portal.

Pero el portal necesita terminar la publicación anterior antes de aceptar la siguiente. Si publicás y actualizás en la misma ráfaga, la segunda llamada puede caer dentro de esa ventana y el portal la rechaza.

Es temporal y te lo decimos como tal: la respuesta trae cuántos segundos conviene esperar. Esperá y volvé a llamar — no perdiste nada y el aviso no se duplica.

⚠️ Es la decisión que conviene tomar en tu código, no a mano: cuando te digamos que el portal todavía está procesando, reintentá con espera en vez de tratarlo como un fallo. El endpoint de publicación tiene el contrato exacto de esa respuesta.

Y hay una segunda decisión, que es de diseño: esperar o preguntar. Si preferís no esperar a ciegas, podés consultarle al portal en qué etapa va — la consulta de estado te la dice.

⚠️ Para un aviso suelto los dos caminos sirven. Para un desarrollo con muchas unidades no: ahí preguntar engaña, y el motivo está en publicar un desarrollo.

Preguntar cuesta una llamada del cupo de tu cliente; esperar es gratis. Por eso la recomendación por defecto no cambia: ante la ventana de procesamiento, reintentá con espera. Consultar el estado es la alternativa para quien prefiera saber en vez de esperar — y conviene reservarla para cuando necesitás decidir algo con esa respuesta.

6 · Pagar por posición (opcional, y no se hace igual en todos los portales)

Hasta acá el aviso está publicado. Dónde aparece en el listado es otra decisión, y los portales que la cobran no la cobran en el mismo momento del flujo: en algunos se elige al publicar —viaja con el paso 3— y en otros después, sobre el aviso ya online.

No tenés que saberlo de memoria: preguntalo. El GET es gratis y te lo dice.

GET  …/publication/{portal}/positioning
PUT  …/publication/{portal}/positioning

El GET siempre contesta dos cosas: con qué se paga la posición en ese portal y dónde se elige. A partir de ahí hay tres caminos:

Lo que te dice el GETQué hacés
se elige acáleer → decidir → PUT, como abajo
se elige al publicarvolvés al paso 3: viaja con la publicación, y el GET te dice en qué campo
el portal no la cobranada: no hay posición que comprar

Cuando se elige acá, el orden es leer, decidir, asignar — nunca asignar a ciegas:

  1. El GET te dice cuánto le queda a tu cliente, dónde está el aviso hoy y, si lo pedís, en qué posición quedaría gastando cada monto.
  2. Decidís vos (o tu usuario). Nosotros no elegimos por él.
  3. El PUT lo aplica y te devuelve la posición real que quedó.

El ?simulate= cuesta una llamada del cupo de tu cliente por cada valor. Pedí los que vas a mostrar, no una curva entera "por si acaso".

Recién publicado puede no haber datos todavía: el portal tarda en indexar el aviso. El saldo y la posición vienen igual; la simulación llega con unavailable y su motivo. Volvé a pedirla en un rato.

Detalle completo: pagar por posición. Lo propio de cada portal —con qué paga, qué cupo tiene— está en Publicación.

7 · Dar de baja

DELETE …/publication/{portal} baja el aviso de ese portal. Es idempotente: si ya no estaba, contesta bien igual, así que no tenés que llevar la cuenta.

Y ojo con la distinción, que es la que más confunde: bajar el aviso, desconectar la cuenta y borrar el cliente son tres cosas distintas y sólo la primera baja la publicación. Está en dar de baja.

El orden importa: qué pasa si lo hacés al revés

Si…Te lo decimos así
publicás antes de que el cliente tenga su fichael error dice que falta declarar al cliente, y cómo
publicás antes de que su cuenta esté conectadael error dice que falta conectar esa cuenta, con el portal nombrado
publicás una propiedad que no cargasteno la encontramos por ese paId

Los tres son errores tempranos y con nombre: te dicen qué paso te salteaste, no "algo falló".

Lo que no tenés que hacer

  • Mapear zonas. Vos mandás tu zona y nosotros resolvemos la del portal. Si una no está mapeada, el verificador te avisa antes de publicar.
  • Llevar la cuenta del cupo. El portal lo informa y te lo pasamos en la respuesta de publicar.
  • Consultar los planes antes de cada publicación. Si el que pediste no está, la respuesta te dice cuáles hay.
  • Reintentar con otro objeto cuando el portal rechaza. Verificá primero: es gratis y te dice lo mismo sin gastar.

Relacionado