Autenticación
Toda llamada lleva una llave en el encabezado. No hay sesión, ni cookies, ni OAuth.
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.
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.
| Permiso | Qué habilita | Por defecto |
|---|---|---|
catalogo.leer | Servicios y valores válidos de la mesa | Sí |
tickets.crear | Registrar tickets nuevos | Sí |
notas.crear | Notas internas — las lee un agente | Sí |
tickets.leer | Consultar y buscar | No |
adjuntos.crear | Subir archivos a un ticket | No |
respuestas.crear | Escribirle al cliente | No |
tickets.actualizar | Cambiar estado y prioridad | No |
tickets.escalar | Pasar un ticket a la cola de otro equipo | No |
contactos.leer | Buscar personas y empresas, con sus teléfonos y correos | No |
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.
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
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.
catalogo.leer
curl https://updesk.cl/api/v1/metadatos \
-H "Authorization: Bearer $UPDESK_KEY"
{
"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.
catalogo.leer
{
"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
tickets.crear
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" }'
{
"id": "cmudi24wq00039kr6yb6myymu",
"codigo": "#0043",
"numero": 43,
"estado": "NUEVO",
"prioridad": "MEDIO",
"tipo": "INCIDENCIA",
"referenciaExterna": "call-8891",
"url": "https://updesk.cl/tickets/cmudi24wq00039kr6yb6myymu"
}
Campos
| Campo | Tipo | Notas |
|---|---|---|
titulo | texto | Obligatorio. 3 a 255 caracteres |
descripcion | texto | Obligatorio |
solicitante | objeto | Obligatorio. Ver abajo |
servicioId | texto | Del catálogo. Completa mesa, tipo y prioridad |
mesaId | texto | Sólo si no hay servicio, o para forzar otra |
estado | texto | Estado inicial. Sólo uno abierto de la mesa; por defecto NUEVO |
elementoId | texto | Elemento afectado del mapa de servicios |
tipo | texto | Se valida contra los de esa mesa |
prioridad | texto | Se valida contra las de esa mesa |
categoriaId | texto | Del catálogo |
canal | texto | Por defecto API |
referenciaExterna | texto | Tu identificador. Se puede buscar por él, y no se crea dos veces (abajo) |
campos | objeto | Campos 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.
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.
"solicitante": { "telefono": "+56912345678", "nombre": "Luis Pérez" }
"solicitante": { "correo": "luis.perez@esval.cl" }
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ón | Respuesta |
|---|---|
| Misma clave, mismo cuerpo | Devuelve la respuesta anterior. No crea otro |
| Misma clave, otro cuerpo | 409 — es un error tuyo, no un reintento |
| Pasadas 2 horas | La 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
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.
tickets.leer
# 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.
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
tickets.actualizar
{
"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.
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
notas.crear
respuestas.crear
{
"cuerpo": "Se ejecutó el reinicio del túnel. Sin efecto."
}
Una nota la lee un agente. Una respuesta le llega al cliente.
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.
adjuntos.crear
{
"nombre": "captura.png",
"tipoMime": "image/png",
"bytes": 84213
}
→ { "urlDeSubida": "…", "ruta": "…" }
# 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
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.
{
"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.
hastadice 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.desdeexiste 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
tickets.escalar
{
"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.
contactos.leer
contactos.leer
{
"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"
}
qbusca por nombre sin distinguir tildes ni mayúsculas. Hasta 20 resultados.telefonoacepta 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.
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.
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
const esperada = crypto .createHmac("sha256", SECRETO) .update(timestamp + cuerpoCrudo) .digest("base64") if (esperada !== firmaRecibida) return 401
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
{
"error": {
"codigo": "prioridad_desconocida",
"mensaje": "Prioridad «P3» no existe en esta mesa."
}
}
| Código | Cuándo |
|---|---|
| 401 | Falta la llave, o no existe |
| 403 | La llave existe pero le falta el permiso, venció o fue revocada |
| 404 | El ticket no existe o está fuera del alcance de tu llave |
| 409 | Idempotency-Key reusada con otro cuerpo |
| 422 | Validación: falta un campo, o el valor no existe en esa mesa |
| 429 | Lí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.
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.
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.