Roldesk REST API

Crea un token en Configuración → Desarrollador (propietario/administrador, plan Professional) y luego verifícalo:

curl https://www.roldesk.com/api/v1/me \
  -H "Authorization: Bearer rk_live_…"

Lista tus órdenes de trabajo:

curl "https://www.roldesk.com/api/v1/work-orders?limit=25" \
  -H "Authorization: Bearer rk_live_…"

Envía tu token como credencial Bearer en cada solicitud: Authorization: Bearer rk_live_…. Los tokens se muestran una sola vez al crearlos — guárdalos de forma segura. Un propietario o administrador puede crearlos y revocarlos en Configuración → Desarrollador, y están disponibles en el plan Professional. La API es de servidor a servidor (sin cookies ni credenciales CORS del navegador).

Cada token recibe un subconjunto de alcances. Un alcance tiene el formato {group}:{read|write}. Un token nunca puede exceder lo que permite tu plan.

Las listas se paginan por cursor. Pasa limit (1–100, por defecto 25) y starting_after (el next_cursor de la respuesta anterior).

{
  "data": [ { "object": "work_order", "id": "…", … } ],
  "has_more": true,
  "next_cursor": "eyJ…"
}

La mayoría de las listas también aceptan filtros permitidos como status, account_id y updated_since.

Las creaciones aceptan un encabezado Idempotency-Key — reintentar con la misma clave devuelve el resultado original en lugar de crear un duplicado. Las actualizaciones aceptan expected_updated_at para control de concurrencia optimista; un valor desactualizado devuelve 409.

curl -X POST https://www.roldesk.com/api/v1/customers \
  -H "Authorization: Bearer rk_live_…" \
  -H "Idempotency-Key: create-acme-2026-08" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "email": "ops@acme.com"}'

Los errores usan una estructura consistente con el estado HTTP correcto:

{ "error": { "type": "…", "code": "…", "message": "…", "param": "…" } }

En lugar de consultar continuamente, suscríbete a eventos y los enviaremos por POST a tu servidor cuando ocurran. Agrega un endpoint en Configuración → Desarrollador (o mediante la API para integraciones tipo Zapier), elige los eventos que te interesan y guarda el secreto de firma que mostramos una sola vez.

Cada entrega es un POST JSON con estos encabezados:

Roldesk-Event:      contract.renewed
Roldesk-Delivery:   <delivery id>
Roldesk-Signature:  t=<unix_ts>,v1=<hex hmac-sha256>

El cuerpo es un evento ligero — obtén el objeto completo desde la API REST usando su id:

{ "id": "…", "type": "contract.renewed", "created": "2026-08-10T12:00:00Z",
  "data": { "object": "contract", "id": "…" } }

Verifica la firma antes de confiar en una entrega (Node):

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Las entregas fallidas se reintentan con retroceso (hasta 6 intentos); un endpoint que sigue fallando se desactiva automáticamente. Eventos disponibles:

Zapier y no-code: usa el patrón REST Hook — tu Zap se suscribe con POST /api/v1/webhooks (un token con webhooks:write) y se da de baja con DELETE /api/v1/webhooks/{id}.

La definición completa legible por máquina está en /api/v1/openapi.json (OpenAPI 3.1) — impórtala en Postman, Insomnia o tu herramienta de generación de código.

¿Eres nuevo? Hay guías paso a paso en el Centro de ayuda — primeros pasos, webhooks, Zapier y recetas comunes.