Skip to main content
POST
Mover un ticket de etapa
Moves a ticket to a different stage. This is the endpoint to use for pipeline transitions — it runs the pipeline’s own rules and reports what the move triggered, which a plain field write through PATCH /v1/crm/tickets/:id does not. The optional context fields (prioridad, contexto, problema, recomendaciones) are recorded with the transition and surfaced to whoever picks the ticket up next. They are especially useful when an automation hands a ticket over to a human stage.

Endpoint

Required scope

crm:tickets:write

Headers

Path parameters

Body

Example request

Response

200 OK

400 Bad Request

Missing or malformed stage_id, or a property the endpoint does not accept.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the crm:tickets:write scope.

404 Not Found

No ticket with that id, or the ticket belongs to a different company.

Operational notes

  • Moving to the current stage is a no-op that returns 200 with stage_changed: false. Safe to retry.
  • Watch is_human_stage if your automation must stop talking once a person takes over the conversation.
  • Stage ids are opaque. There is no public endpoint for listing pipelines and stages yet — read them from the portal, or capture them from the stage field of tickets you already fetched.

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Path Parameters

id
string
required

Body

application/json
stage_id
string
required

Etapa de destino dentro del pipeline

prioridad
string

Prioridad reportada al mover la etapa

contexto
string

Contexto del movimiento

problema
string

Problema detectado

recomendaciones
string

Recomendaciones para el operador

Response

200 - application/json
ticket
object
required
current_stage_id
string
required

Etapa resultante

stage_changed
boolean
required

false si el ticket ya estaba en esa etapa; la llamada es idempotente

previous_stage_id
string

Etapa previa al movimiento

is_human_stage
boolean

La etapa de destino espera intervención de una persona

stage_type
string
next_stage_to_set
string

Presente cuando las reglas del pipeline piden avanzar de nuevo