Referencia de API

Todos los endpoints de la API pública v1, generados directamente desde el código: nunca se escriben a mano. Autentica cada request con el header X-API-Key (ver Autenticación).

messages

POST

/messages

Enviar un mensaje de WhatsApp a un lead

Envía un mensaje de WhatsApp a un lead. Enviá **una** de dos cosas: - content → texto libre. Solo funciona con la **ventana de servicio de 24h abierta** (el lead te escribió en las últimas 24h); si no, se responde 422 ventana_cerrada. - template_name (+ variables opcionales) → una plantilla **aprobada**, que funciona también fuera de la ventana de 24h. El mensaje sale por el único punto de salida del sistema (dispatch): respeta el opt-out del lead (422 contacto_baja). El workspace se ancla de la API key. Soporta el header opcional Idempotency-Key para reintentos seguros (un retry con la misma key NO reenvía el WhatsApp: devuelve la respuesta de la primera vez).

Cuerpo del request

Campo	Tipo	Requerido	Descripción
`lead_id`	`string (uuid)`	Sí	ID del lead a contactar (= contacts.id)
`content`	`string`	No	Texto libre a enviar. Requiere ventana de 24h abierta. Excluyente con `template_name`.
`template_name`	`string`	No	Nombre de un template APROBADO (ver `GET /templates`). Bypassa la ventana. Excluyente con `content`.
`variables`	`string[]`	No	Valores posicionales del template: `variables[0]` → {{1}}, `variables[1]` → {{2}}, … Solo con `template_name`.

Ejemplo de body

{
  "lead_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "content": "Hola Tony, te confirmo tu cita del martes a las 15:00. ¡Nos vemos!"
}

Ejemplo

curl -X POST https://app.asira.io/api/public/v1/messages \
  -H "X-API-Key: sygk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","content":"Hola Tony, te confirmo tu cita del martes a las 15:00. ¡Nos vemos!"}'

Respuestas

200

Mensaje enviado

{
  "success": true,
  "channel": "whatsapp",
  "type": "text",
  "provider_message_id": "wamid.HBgLNTY5..."
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en este workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

422

Body inválido (JSON válido pero no pasa el schema: falta lead_id, o no se envió exactamente uno de content/template_name) — código validation_error. También cubre reglas de negocio: ventana_cerrada (texto libre sin ventana de 24h), contacto_baja (lead con opt-out) o template_no_disponible (no hay un template aprobado con ese nombre).

{
  "error": {
    "code": "ventana_cerrada",
    "message": "No hay una ventana de 24h abierta con este lead. Enviá una plantilla aprobada (`template_name`) para reabrir la conversación."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

502

El proveedor de WhatsApp rechazó o falló el envío

{
  "error": {
    "code": "envio_fallido",
    "message": "No se pudo enviar el mensaje."
  }
}

templates

GET

/templates

Templates de WhatsApp

Lista los templates de WhatsApp del workspace. Por defecto devuelve los **aprobados** (los únicos que POST /messages puede enviar con template_name); pasá ?status= para ver otros estados. Paginado con limit/offset.

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
`limit`	`integer`	No	Cantidad máxima de resultados (1–100, default 50)
`offset`	`integer`	No	Cantidad de resultados a saltar (default 0)
`status`	`enum ("draft", "submitted", "approved", "rejected", "paused")`	No	Filtra por estado. Default: `approved` (los enviables).

Ejemplo

curl -X GET https://app.asira.io/api/public/v1/templates \
  -H "X-API-Key: sygk_live_tu_api_key"

Respuestas

200

Listado de templates paginado

{
  "data": [
    {
      "id": "b2c3d4e5-6789-40ab-8cde-1234567890ab",
      "name": "recordatorio_cita",
      "language": "es",
      "category": "utility",
      "status": "approved",
      "body_template": "Hola {{1}}, te recordamos tu cita el {{2}}. ¡Te esperamos!",
      "variables": [
        "1",
        "2"
      ],
      "approved_at": "2026-07-01T14:30:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

422

Query params inválidos (ej. limit/offset no numéricos o fuera de rango, o status con un valor no soportado)

{
  "error": {
    "code": "validation_error",
    "message": "Number must be less than or equal to 100"
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

leads

POST

/leads/{id}/tags

Asignar tag(s) a un lead

Asigna uno o más tags a un lead. Enviá tag (uno) o tags (varios). Los tags ya presentes en el lead se omiten sin error (idempotente). **Solo se pueden asignar tags que ya existen en el catálogo del workspace** (GET /tags): si alguno no existe se responde 422 tag_inexistente — para crear un tag nuevo, usá el panel. El workspace se ancla de la API key.

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (= contacts.id)

Cuerpo del request

Campo	Tipo	Requerido	Descripción
`tag`	`string`	No	Un solo tag a asignar
`tags`	`string[]`	No	Varios tags a asignar. Usá `tag` para uno solo o `tags` para varios.

Ejemplo de body

{
  "tags": [
    "vip",
    "seguimiento"
  ]
}

Ejemplo

curl -X POST https://app.asira.io/api/public/v1/leads/{id}/tags \
  -H "X-API-Key: sygk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tags":["vip","seguimiento"]}'

Respuestas

200

Tags asignados (set resultante del lead)

{
  "success": true,
  "tags": [
    "vip",
    "seguimiento"
  ],
  "added": [
    "vip"
  ]
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en este workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

409

El lead se editó de forma concurrente; reintentá

{
  "error": {
    "code": "conflict",
    "message": "El lead se editó de forma concurrente; reintentá."
  }
}

422

Body inválido (JSON válido pero no pasa el schema: falta tag/tags o formato incorrecto) — código validation_error; o algún tag no existe en el catálogo del workspace — código tag_inexistente.

{
  "error": {
    "code": "tag_inexistente",
    "message": "El tag «premium» no existe en el catálogo del workspace. Creá el tag primero desde el panel."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

DELETE

/leads/{id}/tags/{tag}

Remover un tag de un lead

Quita un tag de un lead. {tag} es el nombre del tag (URL-encodeado). Idempotente: si el lead no tenía el tag responde 200 con removed: false. Solo afecta a este lead; no borra el tag de otros leads ni del catálogo. El workspace se ancla de la API key.

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (= contacts.id)
`tag`	`string`	Sí	Nombre del tag a remover (URL-encodeado)

Ejemplo

curl -X DELETE https://app.asira.io/api/public/v1/leads/{id}/tags/{tag} \
  -H "X-API-Key: sygk_live_tu_api_key"

Respuestas

200

Tag removido (o no estaba presente)

{
  "success": true,
  "removed": true,
  "tags": [
    "seguimiento"
  ]
}

400

Parámetros inválidos (id no-UUID o tag vacío)

{
  "error": {
    "code": "validation_error",
    "message": "El id del lead debe ser un UUID."
  }
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en este workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

409

El lead se editó de forma concurrente; reintentá

{
  "error": {
    "code": "conflict",
    "message": "El lead se editó de forma concurrente; reintentá."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

GET

/leads/{id}/meetings

Reuniones de un lead

Lista las reuniones (citas de calendario) de un lead, de la más reciente a la más antigua. Incluye tipo, fecha, estado y ejecutivo. Filtro opcional ?status= (coma-separado). Paginado con limit/offset. El workspace se ancla de la API key; si el lead no es de este workspace se responde 404.

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (= contacts.id)

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
`limit`	`integer`	No	Cantidad máxima de resultados (1–100, default 50)
`offset`	`integer`	No	Cantidad de resultados a saltar (default 0)
`status`	`string`	No	Filtra por estado(s), separados por coma. Valores: booked, confirmed, completed, cancelled, no_show. Ej: `status=booked,confirmed`.

Ejemplo

curl -X GET https://app.asira.io/api/public/v1/leads/{id}/meetings \
  -H "X-API-Key: sygk_live_tu_api_key"

Respuestas

200

Listado de reuniones del lead, paginado

{
  "data": [
    {
      "id": "a1b2c3d4-5678-40ab-9cde-1234567890ab",
      "status": "booked",
      "scheduled_at": "2026-07-15T17:00:00Z",
      "duration_minutes": 30,
      "type": "Demo 30 min",
      "provider": "google",
      "meeting_url": "https://meet.google.com/abc-defg-hij",
      "host_name": "Pepper Potts",
      "attendee_name": "Tony Stark",
      "attendee_email": "tony.stark@gmail.com",
      "created_at": "2026-07-10T12:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en este workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

422

Query params inválidos (ej. limit/offset no numéricos o fuera de rango)

{
  "error": {
    "code": "validation_error",
    "message": "Number must be less than or equal to 100"
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

GET

/leads

Listar leads

Lista los leads del workspace (más recientes primero, sin archivados). Filtros: q (nombre/teléfono/email), pipeline_id, stage_key. Paginado con limit/offset/has_more.

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
`limit`	`integer`	No	Cantidad máxima de resultados (1–100, default 50)
`offset`	`integer`	No	Cantidad de resultados a saltar (default 0)
`q`	`string`	No	Búsqueda libre por nombre, teléfono o email
`pipeline_id`	`string`	No	Filtra por pipeline (grupo)
`stage_key`	`string`	No	Filtra por key de etapa

Ejemplo

curl -X GET https://app.asira.io/api/public/v1/leads \
  -H "X-API-Key: sygk_live_tu_api_key"

Respuestas

200

Listado de leads

{
  "data": [
    {
      "id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b",
      "name": "Tony Stark",
      "phone": "+56912345678",
      "email": "tony@stark.cl",
      "source": "whatsapp",
      "pipeline_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "stage_key": "calificado",
      "stage_label": "Calificado",
      "stage_category": "active",
      "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agent_name": "Agente de ventas",
      "created_at": "2026-07-10T12:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

422

Query params inválidos (ej. limit/offset no numéricos o fuera de rango)

{
  "error": {
    "code": "validation_error",
    "message": "Number must be less than or equal to 100"
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

POST

/leads

Crear lead

Crea un lead y lo rutea a un agente/etapa. El destino se resuelve por precedencia: agent_id explícito → pipeline_id explícito → el Processor (primera regla que matchea) → agente default/activo. El teléfono se normaliza a E.164 y es la identidad del lead (único por workspace): si ya existe un lead ACTIVO con ese teléfono se devuelve 409 con su lead_id. Soporta el header opcional Idempotency-Key para reintentos seguros (un retry con la misma key NO vuelve a crear/rutear el lead: devuelve la respuesta de la primera vez).

Cuerpo del request

Campo	Tipo	Requerido	Descripción
`name`	`string`	No	Nombre del lead
`phone`	`string`	Sí	Teléfono del lead (E.164 o local; se normaliza a E.164)
`email`	`string`	No	Email del lead
`source`	`string`	No	Origen del lead (default: "api")
`metadata`	`object`	No	Metadata arbitraria del lead (se guarda en custom_fields)
`pipeline_id`	`string (uuid)`	No	Pipeline (grupo) donde inscribir el lead. Tiene precedencia sobre el processor.
`agent_id`	`string (uuid)`	No	Agente al que asignar el lead. Tiene precedencia sobre pipeline_id y el processor.

Ejemplo de body

{
  "name": "Tony Stark",
  "phone": "+56912345678",
  "email": "tony@stark.cl",
  "metadata": {
    "rango_sueldo": "$2000-$4000",
    "origen_campania": "meta_ads"
  }
}

Ejemplo

curl -X POST https://app.asira.io/api/public/v1/leads \
  -H "X-API-Key: sygk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tony Stark","phone":"+56912345678","email":"tony@stark.cl","metadata":{"rango_sueldo":"$2000-$4000","origen_campania":"meta_ads"}}'

Respuestas

201

Lead creado y ruteado

{
  "lead": {
    "id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b",
    "name": "Tony Stark",
    "phone": "+56912345678",
    "email": "tony@stark.cl",
    "source": "api",
    "pipeline_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "stage_key": "nuevo",
    "stage_label": "Nuevo",
    "stage_category": "active",
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent_name": "Agente de ventas",
    "created_at": "2026-07-10T12:00:00Z",
    "tags": [],
    "next_contact_at": null,
    "automation_paused": false,
    "variables": [
      {
        "key": "rango_sueldo",
        "label": "Rango de sueldo",
        "type": "text",
        "value": "$2000-$4000"
      }
    ],
    "metadata": {
      "rango_sueldo": "$2000-$4000",
      "origen_campania": "meta_ads"
    }
  },
  "routing": {
    "source": "rule",
    "rule_matched": "Leads de Meta Ads"
  }
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

409

Ya existe un lead activo con ese teléfono

{
  "error": {
    "code": "lead_ya_existe",
    "message": "Ya existe un lead activo con este teléfono."
  },
  "lead_id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b"
}

422

Body inválido (falta phone, email mal formado, agent_id/pipeline_id inexistente)

{
  "error": {
    "code": "validation_error",
    "message": "El agent_id no existe en el workspace."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

GET

/leads/{id}

Obtener lead

Devuelve el lead completo: datos del contacto, etapa/agente, variables tipadas del agente (agent_fields cruzadas con lo recolectado) y metadata de negocio.

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (UUID)

Ejemplo

curl -X GET https://app.asira.io/api/public/v1/leads/{id} \
  -H "X-API-Key: sygk_live_tu_api_key"

Respuestas

200

Lead encontrado

{
  "id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b",
  "name": "Tony Stark",
  "phone": "+56912345678",
  "email": "tony@stark.cl",
  "source": "whatsapp",
  "pipeline_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "stage_key": "calificado",
  "stage_label": "Calificado",
  "stage_category": "active",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_name": "Agente de ventas",
  "created_at": "2026-07-10T12:00:00Z",
  "tags": [
    "vip"
  ],
  "next_contact_at": "2026-07-11T15:00:00Z",
  "automation_paused": false,
  "variables": [
    {
      "key": "rango_sueldo",
      "label": "Rango de sueldo",
      "type": "text",
      "value": "$2000-$4000"
    },
    {
      "key": "edad",
      "label": "Edad",
      "type": "number",
      "value": null
    }
  ],
  "metadata": {
    "rango_sueldo": "$2000-$4000",
    "origen_campania": "meta_ads"
  }
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en el workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

PATCH

/leads/{id}

Actualizar lead

Actualiza campos del lead. name/email/source se reemplazan; metadata y variables se fusionan de forma shallow en las variables existentes (las claves no incluidas se preservan). Devuelve el lead actualizado.

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (UUID)

Cuerpo del request

Campo	Tipo	Requerido	Descripción
`name`	`string`	No	Nombre del lead
`email`	`string`	No	Email del lead (null para limpiarlo)
`source`	`string`	No	Origen del lead
`metadata`	`object`	No	Pares clave-valor a fusionar (shallow) en custom_fields
`variables`	`object`	No	Valores de variables del agente a fusionar (shallow) en custom_fields

Ejemplo de body

{
  "email": "tony.stark@gmail.com",
  "variables": {
    "rango_sueldo": "$4000-$6000"
  },
  "metadata": {
    "contactado_externamente": true
  }
}

Ejemplo

curl -X PATCH https://app.asira.io/api/public/v1/leads/{id} \
  -H "X-API-Key: sygk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"tony.stark@gmail.com","variables":{"rango_sueldo":"$4000-$6000"},"metadata":{"contactado_externamente":true}}'

Respuestas

200

Lead actualizado

{
  "id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b",
  "name": "Tony Stark",
  "phone": "+56912345678",
  "email": "tony.stark@gmail.com",
  "source": "whatsapp",
  "pipeline_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "stage_key": "calificado",
  "stage_label": "Calificado",
  "stage_category": "active",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_name": "Agente de ventas",
  "created_at": "2026-07-10T12:00:00Z",
  "tags": [
    "vip"
  ],
  "next_contact_at": "2026-07-11T15:00:00Z",
  "automation_paused": false,
  "variables": [
    {
      "key": "rango_sueldo",
      "label": "Rango de sueldo",
      "type": "text",
      "value": "$4000-$6000"
    }
  ],
  "metadata": {
    "rango_sueldo": "$4000-$6000",
    "origen_campania": "meta_ads",
    "contactado_externamente": true
  }
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en el workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

422

Body inválido o sin campos para actualizar

{
  "error": {
    "code": "validation_error",
    "message": "No se proporcionaron campos para actualizar."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

GET

/leads/{id}/history

Historial del lead (timeline)

Devuelve la línea de tiempo cronológica del lead (más reciente primero): mensajes de WhatsApp, actividades del sistema (cambios de etapa, transfers), reuniones y tareas. Filtra con channel=whatsapp o channel=system (coma-separado).

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (UUID)

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
`channel`	`string`	No	Filtro de canales coma-separado: whatsapp \| system. Default: ambos
`limit`	`integer`	No	Máximo de ítems (1–200, default 50)
`offset`	`integer`	No	Offset (default 0)

Ejemplo

curl -X GET https://app.asira.io/api/public/v1/leads/{id}/history \
  -H "X-API-Key: sygk_live_tu_api_key"

Respuestas

200

Timeline del lead

{
  "lead": {
    "id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b",
    "name": "Tony Stark",
    "phone": "+56912345678",
    "email": "tony@stark.cl",
    "source": "whatsapp",
    "created_at": "2026-07-10T08:00:00Z"
  },
  "data": [
    {
      "type": "message",
      "id": "11111111-1111-1111-1111-111111111111",
      "channel": "whatsapp",
      "direction": "inbound",
      "content": "Hola, quiero más info de precios",
      "message_type": "text",
      "media": null,
      "status": "read",
      "provider_message_id": "wamid.HBgL...",
      "timestamp": "2026-07-10T09:05:00Z"
    },
    {
      "type": "activity",
      "id": "22222222-2222-2222-2222-222222222222",
      "channel": "system",
      "activity_type": "state_change",
      "title": "Etapa: nuevo → calificado",
      "payload": {
        "scope": "pipeline",
        "from": "nuevo",
        "to": "calificado",
        "trigger": "field_criteria"
      },
      "timestamp": "2026-07-10T09:06:00Z"
    },
    {
      "type": "meeting",
      "id": "55555555-5555-5555-5555-555555555555",
      "channel": "system",
      "status": "booked",
      "scheduled_at": "2026-07-15T17:00:00Z",
      "timestamp": "2026-07-10T09:10:00Z"
    },
    {
      "type": "task",
      "id": "66666666-6666-6666-6666-666666666666",
      "channel": "system",
      "status": "done",
      "kind": "followup",
      "title": "Etapa → Calificado",
      "reasoning": "El lead confirmó presupuesto y urgencia",
      "scheduled_for": null,
      "done_at": "2026-07-10T09:06:00Z",
      "timestamp": "2026-07-10T09:06:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en el workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

422

Query params inválidos (ej. limit/offset no numéricos o fuera de rango)

{
  "error": {
    "code": "validation_error",
    "message": "Number must be less than or equal to 200"
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

POST

/leads/{id}/status

Mover etapa del lead

Mueve el lead a otra etapa de su pipeline (adelante o atrás). Indica la etapa por stage_key o stage_id. Corre por el motor de pipeline (registra la transición y ejecuta los hooks de la etapa).

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
`id`	`string (uuid)`	Sí	ID del lead (UUID)

Cuerpo del request

Campo	Tipo	Requerido	Descripción
`stage_key`	`string`	No	Key de la etapa destino (usar esta O stage_id)
`stage_id`	`string (uuid)`	No	ID de la etapa destino (alternativa a stage_key)
`reason`	`string`	No	Motivo del cambio (queda en el event y en la tarjeta del lead)

Ejemplo de body

{
  "stage_key": "calificado",
  "reason": "Confirmó presupuesto y urgencia"
}

Ejemplo

curl -X POST https://app.asira.io/api/public/v1/leads/{id}/status \
  -H "X-API-Key: sygk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"stage_key":"calificado","reason":"Confirmó presupuesto y urgencia"}'

Respuestas

200

Lead movido de etapa

{
  "id": "5b8f0e2c-1a3d-4e5f-9a0b-1c2d3e4f5a6b",
  "from": "nuevo",
  "to": "calificado",
  "stage": {
    "key": "calificado",
    "label": "Calificado",
    "category": "active"
  }
}

401

API key faltante, inválida o revocada

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

404

Lead no encontrado en el workspace

{
  "error": {
    "code": "not_found",
    "message": "Lead no encontrado."
  }
}

422

Transición inválida: falta stage_key/stage_id, la etapa no existe en el pipeline del lead, o ya es la etapa actual

{
  "error": {
    "code": "transicion_invalida",
    "message": "La etapa \"cerrado\" no existe en este pipeline. Etapas válidas: nuevo, calificado, propuesta."
  }
}

429

Límite diario de requests alcanzado (5000/día por key)

{
  "error": {
    "code": "rate_limited",
    "message": "Límite diario de 5000 requests alcanzado para esta API key. Se resetea a medianoche (UTC)."
  }
}

Referencia de API

messages

Enviar un mensaje de WhatsApp a un lead

templates

Templates de WhatsApp

tags

Catálogo de tags del workspace

leads

Asignar tag(s) a un lead

Remover un tag de un lead

Reuniones de un lead

Listar leads

Crear lead

Obtener lead

Actualizar lead

Historial del lead (timeline)

Mover etapa del lead