Conceptos
Etapas
El recorrido de una operación, sus compuertas, y por qué no es igual en Panamá que en México.
Cada operación recorre una lista de etapas propia de su tipo. La API devuelve siempre dos campos, y hacen cosas distintas:
| campo | para qué |
|---|---|
stage | el valor estable, en inglés. Es el contrato: guarda esto, compara esto. |
stage_label | lo que se le muestra a una persona, en su idioma y en el registro de su mercado. Cambia; no lo compares. |
is_terminal | si la operación ya está cerrada. |
Los tres recorridos
Captación (sell) — el propietario que quiere vender o alquilar su bien:
new → negociacion → listing_signed → on_market → sold | rented
Compra (buy):
interested → viewing → offer → signed_promise → bank_processing → public_deed → won
Alquiler (rent):
interested → viewing → application → lease_signing → key_handover → rented
bank_processing solo aparece cuando la compra es financiada. El subtipo de
la operación (contado, financiado…) es lo que decide qué etapas y qué
documentos entran en juego.
Avanzar es una transición, no una escritura
PATCH /operations/{id} con un stage nuevo no escribe la columna. Pasa
por las mismas reglas que el botón « Avanzar » del Pipeline:
- un paso a la vez. Saltarse una etapa es
422 invalid_transition, con la etapa esperada endetails.expected_stage. - la compuerta de la etapa actual tiene que estar pasada. Si no,
422 stage_gate_blockedy la lista de lo que falta endetails.pending_actions. lostexigelost_reason.- una operación cerrada no se mueve.
details.reason lleva la variante legible por máquina: invalid_stage,
invalid_transition, stage_gate_blocked, operation_closed,
lost_reason_required, db_gate_blocked.
La base de datos aplica compuertas propias por encima de estas — por ejemplo,
un alquiler no cierra sin el depósito pagado. Aparecen como 422 con
details.reason = "db_gate_blocked".
La excepción es POST /operations: ahí stage es un estado inicial, no una
transición, y no está bloqueado. Así una agencia puede importar su cartera con
negocios que ya venían a mitad del embudo. Todo lo que pasa después de crearla
sí obedece las reglas de arriba.
Por qué el recorrido cambia de país a país
Orkasa opera en Panamá, Costa Rica, México y Colombia. Lo que cambia entre esos mercados no es el software: es el trámite. Un cierre panameño pasa por el Registro Público y sus paz y salvos; uno costarricense por el estudio registral, el plano catastrado y — si el bien está en zona marítimo-terrestre — el contrato de concesión.
Por eso las etapas se resuelven contra el Market Pack de la agencia, que
define el vocabulario, los documentos exigidos y el registro del idioma (tuteo o
usted). Tu integración no necesita saber en qué país está: pide stage para
comparar y stage_label para mostrar, y el pack hace el resto.