Conceptos

La operación

La unidad que se trabaja, se mueve y se cierra.

Un contacto no es un negocio. Una propiedad tampoco. Lo que una inmobiliaria trabaja de verdad es una intención concreta de una persona concreta: esta señora quiere comprar, este señor quiere alquilar, este propietario quiere vender. Eso es una operación, y es el objeto alrededor del cual gira toda la API.

Qué cuelga de ella#

lead (la persona)
 └─ operación (buy · rent · sell)
     ├─ etapa + agente asignado
     ├─ oportunidades → propiedades candidatas
     ├─ visitas
     ├─ ofertas
     └─ documentos y firmas

Una propiedad no pertenece a la operación: se relaciona con ella a través de una oportunidad. Por eso un mismo apartamento puede estar en la operación de tres compradores a la vez sin duplicarse, y por eso una operación de compra puede ir estrechándose de seis candidatas a una sin perder el historial.

Una operación abierta por tipo#

Un lead tiene como máximo una operación abierta por tipo. Si Ana ya tiene una operación buy abierta y vuelve a escribir preguntando por otro apartamento, no se abre un segundo negocio: se añade una oportunidad más.

Eso tiene una consecuencia directa en la API:

curl -X POST "$ORKASA_API/operations" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "lead_id": "4af8…", "operation_type": "buy" }'

devuelve 200 con la operación que ya existía, no un 409 ni un duplicado. 201 significa que se creó ahora. Un POST repetido es seguro: es la forma normal de escribir un Zap del tipo find-or-create.

Demanda y oferta#

El tipo de operación decide de qué lado del mercado está el lead, y no hay un campo aparte que lo diga:

POST /leads acepta buy y rent. sell se rechaza con 422, y es deliberado: una captación se negocia con un propietario y termina en un mandato firmado; no empieza nunca con una llamada a la API, y forzarla dentro de una operación de demanda sería peor que negarla.

Una operación no se cierra por descuido#

Los estados terminales son won · sold · rented y lost · expired · cancelled. Solo se llega a los primeros desde la última etapa activa del recorrido, con su compuerta pasada: no se gana un negocio que nunca se trabajó. Los segundos se alcanzan desde cualquier punto — un negocio puede morir en cualquier momento — y lost exige su lost_reason.

Una operación cerrada ya no se mueve: cualquier intento devuelve 422 con details.reason = "operation_closed".