orkasa
ENEntrar

Guías

De lead a visita

El recorrido completo con llamadas reales: crear el lead, ver su operación, agendar la visita.

export ORKASA_KEY="ork_live_…"
export ORKASA_API="https://orkasa.app/api/v1"

1. Crear el lead

Una sola llamada hace lo mismo que hace la aplicación: busca o crea el contacto (emparejando por teléfono y correo normalizados), inserta el lead, asigna un agente por turno rotativo, abre la operación y lanza la revisión de listas de sanciones.

curl -X POST "$ORKASA_API/leads" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ana Torrijos",
    "phone": "+507 6123 4567",
    "email": "ana.torrijos@example.com",
    "origin": "web",
    "intent": "primary_residence",
    "budget_max": 250000,
    "bedrooms_min": 2,
    "operation_type": "buy"
  }'
{
  "data": {
    "id": "4af8325e-02c0-4882-8c1c-99e7c4326751",
    "full_name": "Ana Torrijos",
    "temperature": "warm",
    "assigned_agent_id": "6bd960d8-2d5a-43c0-a4cc-abb5e7c481db",
    "contact_id": "5ccee837-bdd6-4bdd-ac43-14c429d96c1a",
    "operation_id": "053655cc-47f4-43fd-9369-6f9dee659a28"
  }
}

Guarda el operation_id: es el hilo del que cuelga todo lo demás.

Cuando todavía no sabes qué quiere

Un correo frío no dice si la persona compra o alquila. Omite operation_type y el lead nace sin operación, con operation_id: null. No queda huérfano: la primera calificación que el CRM confirme sobre él —una tarjeta de detección, o el primer turno calificado del bot— es la que abre la operación.

curl -X POST "$ORKASA_API/leads" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Luis Bernal",
    "email": "luis.bernal@example.com",
    "origin": "email",
    "email_subject": "Consulta",
    "email_body": "Me interesa el apartamento en El Cangrejo, ¿está disponible para alquilar?"
  }'

Manda email_subject y email_body y la IA lee el correo, igual que lee un mensaje entrante de WhatsApp: queda registrado como mensaje en el hilo de la conversación, y la detección emite tarjetas con la intención y los criterios que encontró. Ninguno de los dos campos se guarda en el lead.

Ese trabajo ocurre después de responder. La llamada no se ralentiza por él, y si la detección falla nunca te cuesta el lead: siempre recibes tu 201 y el lead queda en crudo, como si el correo no se hubiera enviado.

2. Ver la operación

curl "$ORKASA_API/operations?lead_id=4af8325e-02c0-4882-8c1c-99e7c4326751&open_only=true" \
  -H "Authorization: Bearer $ORKASA_KEY"
{
  "data": [
    {
      "id": "053655cc-47f4-43fd-9369-6f9dee659a28",
      "operation_type": "buy",
      "flow": "buy",
      "stage": "interested",
      "stage_label": "Interesado",
      "is_terminal": false
    }
  ],
  "meta": { "next_cursor": null, "limit": 25 }
}

Compara siempre contra stage. stage_label es para enseñárselo a una persona — ver Etapas.

3. Agendar la visita

curl -X POST "$ORKASA_API/viewings" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "4af8325e-02c0-4882-8c1c-99e7c4326751",
    "property_id": "b81f2a10-9c4e-4d55-bb0f-1e2f3a4b5c6d",
    "scheduled_at": "2026-09-18T16:00:00-05:00",
    "notes": "Prefiere ver el edificio por dentro antes de la unidad."
  }'

scheduled_at es ISO 8601 y se valida. Manda la zona horaria explícita: una hora sin huso se interpreta, y una visita a las 4 de la tarde que aparece a las 9 de la noche es una visita perdida.

Una visita se aloja en la agencia a través de su lead. Una visita sin lead_id es invisible para la API — no es un error de permisos, sencillamente no existe para ella.

Sigue en De la operación al cierre.