Updesk · API v1

Referencia de la API de Updesk

Para conectar un sistema externo a una mesa de ayuda: registrar incidencias, consultarlas, dejar constancia de lo que se ejecutó y recibir aviso cuando algo cambia.

Base https://updesk.cl/api/v1

Autenticación

Toda llamada lleva una llave en el encabezado. No hay sesión, ni cookies, ni OAuth.

Encabezado
Authorization: Bearer usk_live_7sK2mVp9xQ4nR8tL3wZbY6cH

La llave la emite la mesa, desde Configuración → Integraciones → Llaves de API. No la emite quien integra: si una mesa deja entrar al sistema de un cliente suyo, es la mesa la que la crea y la que la revoca.

El secreto se muestra una vez

Al crearla se ve completa y no vuelve a aparecer: lo que se guarda es su hash. Si se pierde, se revoca y se emite otra. En la lista queda sólo el prefijo — usk_live_7sK2… — para poder reconocerla.

Alcance

Una llave puede acotarse a una empresa. Cuando lo está, la empresa del ticket la impone la credencial y nunca se lee del cuerpo. Si el cuerpo pudiera decirla, la llave de un cliente abriría tickets a nombre de otro. Lo mismo al leer: sólo ve los tickets de su empresa.

Permisos

Cada llave lleva sólo lo que necesita. Quien integra casi siempre necesita menos de lo que pide.

PermisoQué habilitaPor defecto
catalogo.leerServicios y valores válidos de la mesaSí
tickets.crearRegistrar tickets nuevosSí
notas.crearNotas internas — las lee un agenteSí
tickets.leerConsultar y buscarNo
adjuntos.crearSubir archivos a un ticketNo
respuestas.crearEscribirle al clienteNo
tickets.actualizarCambiar estado y prioridadNo
tickets.escalarPasar un ticket a la cola de otro equipoNo
contactos.leerBuscar personas y empresas, con sus teléfonos y correosNo
Los dos últimos salen de la mesa

respuestas.crear le escribe al cliente, y tickets.actualizar permite cerrar. Un sistema que cierra un ticket sin resolver se descubre cuando el cliente reclama que nadie lo atendió.

Existen porque hay integraciones a las que les corresponden — un monitoreo que abre cuando la alerta salta tiene que poder cerrar cuando se normaliza — pero los enciende la mesa a propósito.

Ninguna llave puede asignarle un ticket a una persona ni borrarlo. A quién le toca un ticket es una decisión de personas, y borrar no se delega. Lo que sí se puede, con tickets.escalar, es pasarlo a la cola de un equipo: ver Escalar.

Límite de llamadas

Por llave, configurable por la mesa, 60 por minuto por defecto. Toda respuesta trae el estado de la ventana, no sólo las que fallan.

Respuesta
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

Al pasarse, 429 con Retry-After en segundos. El intento bloqueado no se cuenta: si contara, cada reintento alargaría el castigo y la ventana no se abriría nunca.

Antes de escribir nada: pregunta qué acepta la mesa

Esto no es opcional

Cada mesa puede renombrar sus estados, tipos y prioridades. Si los escribes a mano, funciona con el primer cliente y se rompe en silencio con el segundo, que llamó «En atención» a lo que tú mandas como ABIERTO.

GET /metadatos catalogo.leer
Petición
curl https://updesk.cl/api/v1/metadatos \
  -H "Authorization: Bearer $UPDESK_KEY"
Respuesta
{
  "mesa": { "alcance": "empresa",
            "empresa": { "id": "cmq8…",
                         "nombre": "ESVAL" } },
  "mesas":        [ … ],
  "estados":      [ … ],
  "tipos":        [ … ],
  "prioridades":  [ … ],
  "categorias":   [ … ],
  "campos":       [ … ],
  "canales": ["PORTAL", "EMAIL", "PHONE", … ]
}

Devuelve ids además de nombres. El id es lo estable: renombrar un servicio o una categoría es una operación normal de la mesa y no debe romperte.

GET /servicios catalogo.leer
Respuesta
{
  "servicios": [
    {
      "id": "svc-incidente-ti",
      "nombre": "Incidente TI",
      "mesaId": "cmq8e9xrj000d…",
      "mesa": "Tecnología",
      "porDefecto": {
        "tipo": "INCIDENCIA",
        "prioridad": "MEDIO",
        "categoriaId": "cat-redes"
      }
    }
  ]
}

Lee el catálogo de acá en vez de mantener tu propia copia. Si la mantuvieras, el día que el cliente agregue un servicio tu sistema no lo conocería, y el día que lo renombre tu mapeo por nombre se rompería en silencio.

Mandando sólo servicioId, la mesa completa mesa, tipo, prioridad y categoría con su criterio — el que está configurado y mantenido.

Crear un ticket

POST /tickets tickets.crear
Petición
curl -X POST https://updesk.cl/api/v1/tickets \
  -H "Authorization: Bearer $UPDESK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "titulo": "Sin acceso a la VPN",
    "descripcion": "Reinicié el servicio y no levanta.",
    "servicioId": "svc-incidente-ti",
    "canal": "PHONE",
    "solicitante": {
      "telefono": "+56912345678",
      "nombre": "Luis Pérez"
    },
    "referenciaExterna": "call-8891"
  }'
201 Created
{
  "id": "cmudi24wq00039kr6yb6myymu",
  "codigo": "#0043",
  "numero": 43,
  "estado": "NUEVO",
  "prioridad": "MEDIO",
  "tipo": "INCIDENCIA",
  "referenciaExterna": "call-8891",
  "url": "https://updesk.cl/tickets/cmudi24wq00039kr6yb6myymu"
}

Campos

CampoTipoNotas
titulotextoObligatorio. 3 a 255 caracteres
descripciontextoObligatorio
solicitanteobjetoObligatorio. Ver abajo
servicioIdtextoDel catálogo. Completa mesa, tipo y prioridad
mesaIdtextoSólo si no hay servicio, o para forzar otra
estadotextoEstado inicial. Sólo uno abierto de la mesa; por defecto NUEVO
elementoIdtextoElemento afectado del mapa de servicios
tipotextoSe valida contra los de esa mesa
prioridadtextoSe valida contra las de esa mesa
categoriaIdtextoDel catálogo
canaltextoPor defecto API
referenciaExternatextoTu identificador. Se puede buscar por él, y no se crea dos veces (abajo)
camposobjetoCampos propios de la mesa, por id o por su clave. Lo que no calza vuelve en camposIgnorados

La mesa y la empresa salen de la llave, nunca del cuerpo. Los campos que sobran se rechazan con 422.

La misma referencia es el mismo ticket

Si tu llave ya creó un ticket con esa referenciaExterna, se devuelve ese ticket con 200 y la cabecera Idempotent-Replayed: true, aunque la Idempotency-Key ya haya vencido. Así un reintento después de una caída larga no duplica.

El solicitante puede no existir, y puede no tener correo

Se identifica por correo o teléfono. Sin correo, el nombre pasa a ser obligatorio. Si no existe, se crea como solicitante: no consume licencia, no inicia sesión y no aparece en los selectores de asignación.

Por teléfono
"solicitante": {
  "telefono": "+56912345678",
  "nombre": "Luis Pérez"
}
Por correo
"solicitante": {
  "correo": "luis.perez@esval.cl"
}
Por qué el teléfono importa

Es el caso de quien atiende un teléfono: tiene el número siempre y el correo casi nunca. Zendesk no lo resuelve — ahí el teléfono no identifica a nadie, sólo el correo o el id de usuario. Freshservice sí, y es el modelo que se sigue acá.

La idempotencia no es opcional

Manda siempre Idempotency-Key al crear. Sin ella, un tiempo de espera agotado de tu lado se convierte en dos tickets del mismo incidente.

SituaciónRespuesta
Misma clave, mismo cuerpoDevuelve la respuesta anterior. No crea otro
Misma clave, otro cuerpo409 — es un error tuyo, no un reintento
Pasadas 2 horasLa clave caducó: crea un ticket nuevo

El vencimiento a las dos horas es deliberado, y está tomado de Zendesk: pasado ese rato la misma clave ya no es el reintento de una llamada, es otra incidencia.

Consultar y buscar

GET /tickets/{id} tickets.leer

Acepta el id de Updesk o el código visible: /tickets/#0043. Guardaste uno de los dos y no tienes por qué recordar cuál.

GET /tickets?telefono=… tickets.leer
Ejemplos
# Qué tiene abierto quien está llamando
GET /tickets?telefono=%2B56912345678

# El ticket de mi llamada
GET /tickets?referencia=call-8891

# Incluir los cerrados
GET /tickets?telefono=%2B56912345678&incluirCerrados=true

La búsqueda exige telefono o referencia: listar la mesa entera no está permitido. Por defecto no devuelve cerrados — quien pregunta por teléfono quiere saber qué está pendiente, no el historial.

Esto resuelve «llamé ayer por lo de la VPN»

Y por eso importa más que un aviso: el dato tiene que estar fresco en el momento en que suena el teléfono, no en una copia de hace una hora.

Modificar un ticket

PATCH /tickets/{id} tickets.actualizar
Petición
{
  "estado": "RESUELTO",
  "prioridad": "ALTO",
  "campos": { "cmq8eb5wk0011…": "Definitiva" }
}

Acepta estado, prioridad, categoriaId, servicioId, referenciaExterna, campos (por id o por clave) y los del cierre: resolucion, causaRaizId, causaDetalle, motivoCierre y horas. Un estado marcado como de cierre fija cerradoEn solo; RESUELTO además detiene el reloj del SLA, igual que en la pantalla. Si la mesa exige algo para cerrar y no viene: 422 faltan_campos_para_cerrar.

Queda con tu nombre

Cada cambio entra al historial del ticket con el nombre de tu llave. Un ticket que se cierra solo a las tres de la mañana tiene que poder explicarse desde su propia ficha.

No permite reasignar.

Notas y respuestas

POST /tickets/{id}/notas notas.crear
POST /tickets/{id}/respuestas respuestas.crear
Cuerpo
{
  "cuerpo": "Se ejecutó el reinicio del túnel. Sin efecto."
}

Una nota la lee un agente. Una respuesta le llega al cliente.

Por qué son dos rutas y no un booleano

Zendesk resuelve esto con public: true|false dentro del ticket. Con un booleano, equivocarse en un true le manda al cliente un texto que era interno. Con dos rutas ese error no se puede cometer — y cada una pide su propio permiso.

Para una integración automática, usa notas. Si tu sistema se equivoca, la equivocación la lee alguien de la mesa y no el cliente.

Adjuntos

Dos pasos. El archivo no viaja en el JSON: en base64 crece un tercio y pasa por el servidor de la aplicación, que no es un servidor de archivos. Además el tipo y el tamaño se validan antes de mover un byte.

POST /tickets/{id}/adjuntos/firmar adjuntos.crear
1 · Pedir permiso
{
  "nombre": "captura.png",
  "tipoMime": "image/png",
  "bytes": 84213
}

→ { "urlDeSubida": "…", "ruta": "…" }
2 · Subir y confirmar
# PUT del archivo crudo a urlDeSubida
curl -X PUT "$URL" --data-binary @captura.png

# y después
POST /tickets/#0043/adjuntos
{ "ruta": "…", "nombre": "captura.png",
  "tipoMime": "image/png", "bytes": 84213 }

Si abandonas a mitad, queda un archivo huérfano en el almacenamiento y no un adjunto roto en el ticket.

Ponerse al día

GET /tickets/cambios tickets.leer

Es la red de seguridad del aviso saliente, no su reemplazo: sirve para cuando tu extremo estuvo caído, o para una conciliación diaria.

Respuesta
{
  "tickets": [ … ],
  "cursor": "1790083589937.cmudi24wq0003…",
  "finDeFlujo": true,
  "hasta": "2026-09-23T18:22:00.000Z"
}

Guarda el cursor y mándalo en la vuelta siguiente. Mientras finDeFlujo sea false, quedan páginas.

Tres cosas que conviene saber

  • No se sirve el último minuto. Una fila que se está escribiendo podría entregarse con su fecha ya avanzada y el resto sin confirmar. hasta dice hasta dónde llega la respuesta.
  • Usa el cursor, no desde. Si veinte tickets comparten el mismo milisegundo y la página corta ahí, con fecha se pierden en silencio para siempre. El cursor lleva el id y el corte es exacto. desde existe para la primera llamada.
  • El cursor vuelve aunque no haya nada. Así no tienes que recordar cuál fue la última página con datos.

Escalar

POST /tickets/{id}/escalar tickets.escalar
Petición
{
  "equipoId": "cmuol1pe000189km96ba7v5ok",
  "motivo": "Reinicio ejecutado; el servicio sigue sin responder."
}

Hace lo mismo que el botón «Escalar» de la pantalla: el ticket pasa a la cola del equipo —sin agente, para que lo tome quien corresponda—, empieza a correr el compromiso interno (OLA) de ese equipo si tiene uno, y el motivo queda como nota interna. Los equipos de cada mesa salen de GET /metadatos. El motivo tiene al menos 10 caracteres.

Contactos y empresas

Para saber quién escribe o quién llama. Es de lectura: los datos de un contacto se cambian sólo en Updesk, con auditoría.

GET /contactos?q=nombre · ?telefono=número · ?empresaId=id contactos.leer
GET /contactos/{id} · /empresas?q=nombre · /empresas/{id}/contactos contactos.leer
200 OK
{
  "id": "cmuol1pdt00149km99vjrmpst",
  "empresa": { "id": "cmuol1pdl0010…", "nombre": "XYGO" },
  "nombre": "Augusto Catalán",
  "telefono": "+56912345678",
  "correo": "augusto@xygo.cl",
  "activo": true,
  "puedeAbrirTickets": true,
  "verificado": true,
  "verificadoEn": "2026-09-30T14:02:00.000Z",
  "datosDeContactoCambiadosEn": null,
  "canalPreferido": "WHATSAPP"
}
  • q busca por nombre sin distinguir tildes ni mayúsculas. Hasta 20 resultados.
  • telefono acepta cualquier formato y compara en formato internacional (E.164).
  • verificado: una persona de la mesa confirmó que es quien dice ser. Los contactos que Updesk crea solo —un correo de alguien desconocido, un ticket por API con un teléfono nuevo— nacen sin verificar.
  • datosDeContactoCambiadosEn: la última vez que cambió el teléfono o el correo.
  • Una llave limitada a una empresa sólo ve esa empresa.
Si vas a ejecutar acciones a pedido de quien llama

Manda el código de validación sólo al teléfono o correo que devuelve Updesk en ese momento; no automatices con un contacto sin verificar o inactivo; y no lo hagas si sus datos cambiaron hace poco. Cualquier agente de la mesa puede editar un teléfono.

Avisos salientes

No hay que suscribirse. El aviso se configura como una regla de la mesa, en Configuración → Automatizaciones, con la acción «Avisar a un sistema externo».

Así la mesa decide cuándo — «cuando un ticket de canal PHONE pase a Resuelto» — en vez de elegir de una lista fija de eventos. Hereda los catorce disparadores y todas las condiciones que ya existen, incluidas las de texto.

Lo que recibes
POST https://tu-sistema.cl/eventos
X-Updesk-Timestamp: 2026-09-23T14:22:31.004Z
X-Updesk-Signature: 9mKp…

{
  "evento": "ticket.actualizado",
  "regla": "Avisar al asistente cuando se resuelve",
  "ticket": {
    "codigo": "#0043",
    "estado": "RESUELTO",
    "canal": "PHONE",
    "referenciaExterna": "call-8891"
  },
  "ocurridoEn": "2026-09-23T14:22:31.004Z"
}

Verificar la firma

Node
const esperada = crypto
  .createHmac("sha256", SECRETO)
  .update(timestamp + cuerpoCrudo)
  .digest("base64")

if (esperada !== firmaRecibida) return 401
El timestamp va dentro de lo firmado

No al lado. Si fuera aparte, alguien podría capturar un aviso válido y reenviarlo mañana con la misma firma. Es el esquema de Zendesk, y es el único de los tres que revisamos que además resuelve el reenvío.

  • Sólo se aceptan direcciones https.
  • El aviso sale después de guardar: cuando llega, el ticket ya está actualizado.
  • Si tu extremo falla, la regla no se deshace. El ticket ya cambió.

Errores

Forma
{
  "error": {
    "codigo": "prioridad_desconocida",
    "mensaje": "Prioridad «P3» no existe en esta mesa."
  }
}
CódigoCuándo
401Falta la llave, o no existe
403La llave existe pero le falta el permiso, venció o fue revocada
404El ticket no existe o está fuera del alcance de tu llave
409Idempotency-Key reusada con otro cuerpo
422Validación: falta un campo, o el valor no existe en esa mesa
429Límite excedido. Mira Retry-After

El 403 no es 401 a propósito: la llave se identificó bien, lo que falta es alcance. Reintentar con otra credencial no va a ayudar.

Y el 404 cubre los dos casos — no existe, o no es tuyo — también a propósito: distinguirlos le confirmaría a quien prueba identificadores cuándo acertó uno.

Otras puertas de entrada

La API no es la única forma de que algo llegue a una mesa.

Correo

Cada mesa tiene una dirección — tu-mesa@updesk.dev, o el buzón propio que haya configurado. Un correo entrante crea el ticket, reconoce al solicitante por el remitente, clasifica tipo, impacto y urgencia con IA, reconoce el servicio del catálogo, asigna con las reglas de entrada y arranca el SLA.

Lo que pierdes frente a la API

No hay clave de idempotencia, así que un reintento tuyo duplica el ticket. El asunto y el cuerpo son texto, no campos. Y el solicitante se identifica por correo, no por teléfono.

Power BI

Un token de sólo lectura por mesa entrega el conjunto completo de tickets como una tabla plana, con los tiempos ya calculados en minutos y los campos propios de la mesa como columnas.

Conector Web
https://updesk.cl/api/reports/powerbi?token=pbi_…

Lo que todavía no hay

Se dice acá en vez de dejar que lo descubras probando.

  • Leer los comentarios de un ticket.
  • Descargar un adjunto.
  • Crear o modificar solicitantes fuera de la creación de un ticket.
  • Asignarle un ticket a una persona. Esto es deliberado y no está previsto.
  • Escribir datos de un contacto. Se cambian sólo en Updesk, con auditoría.