orkasa
ENEntrar

Guías

De la operación al cierre

Registrar una oferta, avanzar el pipeline, y qué hacer cuando la compuerta dice que no.

Registrar la oferta

Una oferta se ancla en la operación, no en el lead. El lead_id se toma de ella, y property_id del cuerpo o de la propia operación — si no hay ninguno de los dos, es 422.

curl -X POST "$ORKASA_API/offers" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "053655cc-47f4-43fd-9369-6f9dee659a28",
    "amount": 238000,
    "currency": "USD",
    "notes": "Sujeta a aprobación de crédito."
  }'

Registrar una oferta no la acepta y no mueve la etapa. Son dos gestos distintos a propósito: recibir una propuesta y aceptarla no son la misma decisión, y aceptar tiene consecuencias reales — el bien vuelve a pending y sus publicaciones se pausan.

offer_type sigue al listing_type de la propiedad cuando lo omites. La respuesta trae un public_token: es el enlace compartible de la oferta.

Avanzar la etapa

curl -X PATCH "$ORKASA_API/operations/053655cc-47f4-43fd-9369-6f9dee659a28" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "offer" }'

Un paso a la vez, y con la compuerta de la etapa actual pasada. Si falta algo:

{
  "error": {
    "code": "validation_error",
    "message": "La etapa actual tiene 2 paso(s) pendiente(s).",
    "details": {
      "reason": "stage_gate_blocked",
      "pending_actions": [
        { "id": "propiedadesVisitadas", "label": "Propiedades visitadas" },
        { "id": "favoritaElegida", "label": "Propiedad favorita elegida" }
      ]
    }
  }
}

Nada se escribió. La operación sigue donde estaba, y pending_actions te dice exactamente qué falta.

No existe un endpoint para « marcar estos pasos como hechos ». Es deliberado: marcar precioAcordado pasa la oferta a accepted, lo que despublica el bien; marcar ofertaPreparada crea una oferta y exige un monto. Un « marcar hecho » genérico dejaría que una frase suelta despublique un anuncio. Los pasos se cierran con verbos precisos — registrar una oferta, subir un documento — o a mano en la operación.

Cerrar

won · sold · rented solo se alcanzan desde la última etapa activa del recorrido, con la compuerta pasada. lost se alcanza desde cualquier punto y exige su razón:

curl -X PATCH "$ORKASA_API/operations/053655cc…" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "lost", "lost_reason": "Compró con otra agencia" }'

El cierre dispara el webhook deal_won — ahí es donde engancha la facturación, el aviso al equipo, o lo que venga después. Ver Webhooks.

Importar una cartera que ya viene a mitad de camino

stage en POST /operations no está bloqueado: ahí es un estado inicial, no una transición. Una agencia que llega con negocios en curso los crea en la etapa donde están de verdad.

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

Después de crearla, todo pasa por las reglas normales. Una operación existente nunca se arrastra hacia atrás.