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 | ||
|---|---|---|
| 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 |
| 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 cuatro 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.
| 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. - 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.
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.