Roldesk REST API

Crie um token em Definições → Desenvolvedor (proprietário/administrador, plano Professional) e depois verifique-o:

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

Liste suas ordens de serviço:

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

Envie seu token como credencial Bearer em cada requisição: Authorization: Bearer rk_live_…. Os tokens são exibidos uma única vez na criação — guarde-os com segurança. Um proprietário ou administrador pode criá-los e revogá-los em Definições → Desenvolvedor, e estão disponíveis no plano Professional. A API é de servidor para servidor (sem cookies, sem credenciais CORS do navegador).

Cada token recebe um subconjunto de escopos. Um escopo tem o formato {group}:{read|write}. Um token nunca pode exceder o que seu plano permite.

As listas são paginadas por cursor. Passe limit (1–100, padrão 25) e starting_after (o next_cursor da resposta anterior).

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

A maioria das listas também aceita filtros permitidos como status, account_id e updated_since.

As criações aceitam um cabeçalho Idempotency-Key — repetir com a mesma chave retorna o resultado original em vez de criar uma duplicata. As atualizações aceitam expected_updated_at para concorrência otimista; um valor desatualizado retorna 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"}'

Os erros usam um envelope consistente com o status HTTP correto:

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

Em vez de ficar consultando, assine eventos e nós os enviaremos por POST ao seu servidor assim que acontecerem. Adicione um endpoint em Definições → Desenvolvedor (ou via API para integrações tipo Zapier), escolha os eventos que importam e guarde o segredo de assinatura que exibimos uma única vez.

Cada entrega é um POST JSON com estes cabeçalhos:

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

O corpo é um evento enxuto — busque o objeto completo na API REST usando o id dele:

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

Verifique a assinatura antes de confiar em uma 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));
}

Entregas com falha são repetidas com recuo (até 6 tentativas); um endpoint que continua falhando é desativado automaticamente. Eventos disponíveis:

Zapier e no-code: use o padrão REST Hook — seu Zap assina com POST /api/v1/webhooks (um token com webhooks:write) e cancela a assinatura com DELETE /api/v1/webhooks/{id}.

A definição completa legível por máquina fica em /api/v1/openapi.json (OpenAPI 3.1) — importe-a no Postman, Insomnia ou na sua ferramenta de geração de código.

Começando agora? Há guias passo a passo na Central de ajuda — primeiros passos, webhooks, Zapier e receitas comuns.