orkasa
ESEntrar

Concepts

Stages

An operation's journey, its gates, and why Panama is not Mexico.

Every operation walks a list of stages that belongs to its type. The API always returns two fields, and they do different jobs:

fieldfor
stagethe stable value, in English. This is the contract: store this, compare this.
stage_labelwhat a person is shown, in their language and their market's register. It changes; do not compare it.
is_terminalwhether the operation is already closed.

The three journeys

Listing (sell) — the owner who wants to sell or rent out their property:

new  →  negociacion  →  listing_signed  →  on_market  →  sold | rented

Buying (buy):

interested → viewing → offer → signed_promise → bank_processing → public_deed → won

Renting (rent):

interested → viewing → application → lease_signing → key_handover → rented

bank_processing only appears when the purchase is financed. The operation's subtype (cash, financed…) is what decides which stages and which documents come into play.

Advancing is a transition, not a write

PATCH /operations/{id} with a new stage does not write the column. It goes through the same rules as the Pipeline's "Avanzar" button:

  • one step at a time. Skipping a stage is 422 invalid_transition, with the expected stage in details.expected_stage.
  • the current stage's gate must have passed. Otherwise 422 stage_gate_blocked, with what is missing in details.pending_actions.
  • lost requires lost_reason.
  • a closed operation does not move.

details.reason carries the machine-readable variant: invalid_stage, invalid_transition, stage_gate_blocked, operation_closed, lost_reason_required, db_gate_blocked.

The database enforces gates of its own on top of these — a rental cannot close before the deposit is paid, for example. Those surface as 422 with details.reason = "db_gate_blocked".

The exception is POST /operations: there, stage is an initial state, not a transition, and it is not gated. That is how an agency imports a book of business whose deals are already mid-funnel. Everything after creation does obey the rules above.

Why the journey changes by country

Orkasa operates in Panama, Costa Rica, Mexico and Colombia. What differs between those markets is not the software: it is the paperwork. A Panamanian closing goes through the Registro Público and its clearance certificates; a Costa Rican one through the registry study, the cadastral plan, and — if the property sits in the maritime zone — the concession contract.

So stages resolve against the brokerage's Market Pack, which sets the vocabulary, the required documents and the register of the language (tú or usted). Your integration does not need to know which country it is in: compare stage, display stage_label, and the pack does the rest.