ServiceDesk na API v1 | Desenvolvedores Steel

ServiceDesk na API v1

Listar, ver, abrir, comentar e mover chamados e consultar as fases e o catálogo de serviços, com curl, steel CLI e SDK, respostas de exemplo e os erros de cada operação.

Nesta página

Todas as rotas desta página exigem um token com o módulo ServiceDesk e rodam com as suas permissões no ServiceDesk: agentes veem a fila do workspace, solicitantes só os próprios chamados, como no portal. Os exemplos usam $STEEL_URL e $STEEL_TOKEN (veja Antes da primeira chamada).

Operação	Rota	Escopo	CLI	SDK
Listar chamados	`GET /api/v1/servicedesk/tickets`	`api:read`	`steel sd ticket list`	`servicedesk.tickets.list()`
Ver chamado	`GET /api/v1/servicedesk/tickets/{ticketId}`	`api:read`	`steel sd ticket view`	`servicedesk.tickets.get()`
Abrir chamado	`POST /api/v1/servicedesk/tickets`	`api:write`	`steel sd ticket create`	`servicedesk.tickets.create()`
Comentar	`POST /api/v1/servicedesk/tickets/{ticketId}/comments`	`api:write`	`steel sd ticket comment`	`servicedesk.tickets.comment()`
Mudar de fase	`POST /api/v1/servicedesk/tickets/{ticketId}/phase`	`api:write`	`steel sd ticket move`	`servicedesk.tickets.move()`
Fases	`GET /api/v1/servicedesk/phases`	`api:read`	—	—
Catálogo	`GET /api/v1/servicedesk/catalog`	`api:read`	`steel sd catalog`	`servicedesk.catalog()`

Onde a rota pede {ticketId}, vale o id, o número (123) ou o código (INC-000123).

Listar chamados

Mais novos primeiro. Sem status, só os abertos (fases das categorias NEW, IN_PROGRESS e WAITING).

Parâmetro	Valores
`status`	Categorias de fase, separadas por vírgula: `NEW`, `IN_PROGRESS`, `WAITING`, `RESOLVED`, `CLOSED`, `CANCELED`
`type`	`INCIDENT`, `SERVICE_REQUEST`, `CHANGE`, `PROBLEM` (vírgula para vários)
`assigneeId`	Ids de usuário, `me` (você) ou `unassigned` (sem responsável)
`phaseId`, `priorityId`	Ids, separados por vírgula (até 100)
`q`	Texto no título, na descrição ou no código (até 200 caracteres)
`limit`, `cursor`	Paginação

curl "$STEEL_URL/api/v1/servicedesk/tickets?assigneeId=me&status=NEW,IN_PROGRESS,WAITING&limit=10" \
  -H "Authorization: Bearer $STEEL_TOKEN"

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": "cm2tkt0001",
        "number": 123,
        "code": "INC-000123",
        "type": "INCIDENT",
        "title": "VPN fora do ar na filial",
        "channel": "PORTAL",
        "phaseId": "cm2phs0002",
        "phase": {
          "id": "cm2phs0002",
          "name": "Em atendimento",
          "color": "#2563eb",
          "category": "IN_PROGRESS",
          "completionPercent": 40,
          "position": 2,
          "wipLimit": 0
        },
        "priority": { "id": "cm2pri0002", "name": "P2 – Alta", "level": 2, "color": "#f97316" },
        "assignee": { "id": "cm2usr0001", "name": "Ana Souza", "email": "ana@empresa.com.br", "image": null },
        "requester": { "id": "cm2usr0009", "name": "Bruno Lima", "email": "bruno@empresa.com.br", "image": null },
        "sla": {
          "firstResponse": { "dueAt": "2026-10-18T13:00:00.000Z", "remainingMinutes": null, "percentUsed": null, "state": "met" },
          "resolution": { "dueAt": "2026-10-18T17:00:00.000Z", "remainingMinutes": 45, "percentUsed": 81, "state": "at_risk" }
        },
        "risk": { "level": "HIGH", "score": 78, "factors": [], "breachEtaAt": "2026-10-18T16:40:00.000Z", "computedAt": "2026-10-18T15:30:00.000Z" },
        "tags": ["vpn"],
        "createdAt": "2026-10-18T12:00:00.000Z",
        "updatedAt": "2026-10-18T15:10:00.000Z"
      }
    ],
    "nextCursor": "cm2tkt0001"
  }
}

steel sd ticket list --assignee me
steel sd ticket list --status aguardando --type incidente --all
steel sd ticket list -s "vpn" --json | jq -r '.items[].code'

const page = await steel.servicedesk.tickets.list({
  assigneeId: ['me'],
  status: ['NEW', 'IN_PROGRESS', 'WAITING'],
  limit: 10,
})
if (page.ok) for (const t of page.data.items) console.log(t.code, t.sla.resolution.state)

curl "$STEEL_URL/api/v1/servicedesk/tickets/INC-000123" \
  -H "Authorization: Bearer $STEEL_TOKEN"

steel sd ticket view 123
steel sd ticket view INC-000123 --json

const ticket = await steel.servicedesk.tickets.get('INC-000123')

Campo	Para quê
`description`	Texto do chamado (até 100.000 caracteres)
`serviceId`, `categoryId`, `subcategoryId`	Onde no catálogo; veja Catálogo de serviços
`impactId`, `urgencyId` ou `priorityId`	Prioridade direta ou pela matriz
`assigneeId`, `departmentId`	Responsável e departamento, se você não quer o roteamento
`requesterId`, `customerId`, `companyId`, `contactId`	Quem pediu e para quem
`templateId`	Modelo de chamado
`tags`	Até 30, cada uma com até 50 caracteres
`customFields`	Campos personalizados, `{ "<chave>": valor }`
`changeType`, `changeRisk`, `plannedStartAt`, `plannedEndAt`, `implementationPlan`, `rollbackPlan`, `testPlan`	Mudanças
`rootCause`, `workaround`, `knownError`	Problemas

curl -X POST "$STEEL_URL/api/v1/servicedesk/tickets" \
  -H "Authorization: Bearer $STEEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INCIDENT",
    "title": "VPN fora do ar na filial",
    "description": "Desde as 9h ninguém da filial Centro conecta.",
    "tags": ["vpn", "filial-centro"]
  }'

steel sd ticket create --type incidente --title "VPN fora do ar na filial" \
  --description @descricao.md --tag vpn --tag filial-centro --yes

const created = await steel.servicedesk.tickets.create({
  type: 'INCIDENT',
  title: 'VPN fora do ar na filial',
  tags: ['vpn'],
})
if (created.ok) console.log(created.data.code)

Erro	Quando
`404 SD_CATEGORY_NOT_FOUND`, `SD_PHASE_NOT_FOUND`, `SD_DEPARTMENT_NOT_FOUND`	Um id do corpo não existe neste workspace
`404 SD_CONFIG_NOT_FOUND`	A configuração do ServiceDesk do workspace não foi encontrada. Fale com um administrador do workspace
`422 SD_CUSTOM_FIELD_INVALID`	Um campo personalizado obrigatório faltou ou veio no formato errado
`403 SD_PORTAL_DISABLED`	Você é solicitante e o portal está desligado
`403 SD_TICKET_FORBIDDEN`	Você é solicitante e o tipo não pode ser aberto pelo portal

curl -X POST "$STEEL_URL/api/v1/servicedesk/tickets/INC-000123/comments" \
  -H "Authorization: Bearer $STEEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Link da operadora caiu; previsão de volta às 14h.","visibility":"INTERNAL"}'

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "cm2msg0001",
    "ticketId": "cm2tkt0001",
    "authorKind": "AGENT",
    "author": { "id": "cm2usr0001", "name": "Ana Souza", "email": "ana@empresa.com.br", "image": null },
    "contact": null,
    "visibility": "INTERNAL",
    "channel": "PLATFORM",
    "body": "Link da operadora caiu; previsão de volta às 14h.",
    "attachments": [],
    "mentionedUserIds": [],
    "editedAt": null,
    "createdAt": "2026-10-18T13:05:00.000Z",
    "canEdit": true,
    "editableUntil": "2026-10-18T13:20:00.000Z"
  }
}

steel sd ticket comment 123 -m "Link da operadora caiu" --internal
git log -1 --format=%B | steel sd ticket comment 123 -m @- --yes

await steel.servicedesk.tickets.comment('INC-000123', {
  body: 'Link da operadora caiu; previsão de volta às 14h.',
  visibility: 'INTERNAL',
})

Campo	Para quê
`phaseId`	Fase de destino (obrigatório)
`solution`	Texto da solução, quando a fase resolve o chamado
`solutionClassificationId`	Classificação da solução, quando a fase exige
`comment`	Comentário da mudança (até 2.000 caracteres)

curl -X POST "$STEEL_URL/api/v1/servicedesk/tickets/INC-000123/phase" \
  -H "Authorization: Bearer $STEEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phaseId":"cm2phs0005","solution":"Link restabelecido pela operadora."}'

steel sd ticket move 123 --phase cm2phs0005 --solution @solucao.md --yes

await steel.servicedesk.tickets.move('INC-000123', {
  phaseId: 'cm2phs0005',
  solution: 'Link restabelecido pela operadora.',
})

Erro	Quando e como resolver
`403 SD_NOT_AGENT`	Você é solicitante. Só agentes movem chamados
`422 SD_PHASE_TRANSITION_NOT_ALLOWED`	O fluxo não permite ir da fase atual para essa. Veja as transições em Configurações do ServiceDesk › Fluxos
`422 SD_PHASE_REQUIREMENTS_UNMET`	A fase pede algo que falta (solução, classificação, campo). A mensagem diz o quê
`422 SD_APPROVAL_REQUIRED`	A mudança precisa de aprovação antes
`422 SD_SIGNATURE_REQUIRED`	A fase exige assinatura digital, feita no aplicativo
`404 SD_PHASE_NOT_FOUND`	O `phaseId` não existe neste workspace

curl "$STEEL_URL/api/v1/servicedesk/phases?ticketType=INCIDENT" \
  -H "Authorization: Bearer $STEEL_TOKEN"

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": "cm2phs0001",
        "ticketType": "INCIDENT",
        "name": "Novo",
        "description": null,
        "color": "#64748b",
        "category": "NEW",
        "completionPercent": 0,
        "position": 0,
        "isInitial": true,
        "pausesSla": false,
        "requiresApproval": false,
        "requiredFields": [],
        "wipLimit": 0,
        "active": true,
        "createdAt": "2026-09-21T12:00:00.000Z",
        "updatedAt": "2026-09-21T12:00:00.000Z",
        "nextPhaseIds": ["cm2phs0002", "cm2phs0006"]
      }
    ],
    "nextCursor": null
  }
}

Valor	Significado
`null`	O tipo não tem transições cadastradas: vale qualquer fase ativa do mesmo tipo
`["…"]`	Só estas fases. Transições limitadas a departamentos são conferidas na hora de mover (`SD_PHASE_TRANSITION_NOT_ALLOWED`)
`[]`	Nenhuma saída cadastrada a partir desta fase

curl "$STEEL_URL/api/v1/servicedesk/catalog?ticketType=SERVICE_REQUEST&limit=100" \
  -H "Authorization: Bearer $STEEL_TOKEN"

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": "cm2cat0001",
        "parentId": null,
        "level": "CATEGORY",
        "name": "Acessos",
        "description": null,
        "icon": null,
        "ticketTypes": ["SERVICE_REQUEST"],
        "departmentId": null,
        "slaPolicyId": null,
        "portalVisible": true,
        "active": true,
        "position": 0,
        "createdAt": "2026-09-01T12:00:00.000Z",
        "updatedAt": "2026-09-01T12:00:00.000Z"
      },
      {
        "id": "cm2svc0007",
        "parentId": "cm2cat0001",
        "level": "SERVICE",
        "name": "Criar usuário na VPN",
        "ticketTypes": ["SERVICE_REQUEST"],
        "portalVisible": true,
        "active": true,
        "position": 3
      }
    ],
    "nextCursor": null
  }
}

steel sd catalog --type requisicao --all

const catalog = await steel.servicedesk.catalog({ ticketType: 'SERVICE_REQUEST', limit: 100 })

- name: Abrir chamado no Steel
  if: failure()
  env:
    STEEL_URL: https://homologacao.stratustelecom.com.br
    STEEL_TOKEN: ${{ secrets.STEEL_TOKEN }}
  run: |
    steel sd ticket create --type incidente \
      --title "Deploy falhou: ${{ github.repository }}@${{ github.sha }}" \
      --description "Execução: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
      --yes

steel sd ticket list --assignee me --all --json \
  | jq -r '.items[] | select(.sla.resolution.state == "at_risk" or .sla.resolution.state == "breached") | "\(.code)  \(.title)"'

Sintoma	O que fazer
A lista não traz chamados resolvidos	Sem `status`, só os abertos voltam. Passe `status=RESOLVED,CLOSED`
A lista vem vazia, mas o chamado existe	Você é solicitante no ServiceDesk e vê só os seus, ou os filtros se anulam (`assigneeId=unassigned` com `assigneeId=me`)
`403 API_TOKEN_MODULE_NOT_ALLOWED`	O token não tem o módulo ServiceDesk
O chamado abriu com prioridade ou responsável diferente do enviado	Uma automação ou regra de roteamento do workspace mudou depois da abertura, como no aplicativo
`422 SD_CUSTOM_FIELD_INVALID`	A chave é a Chave do campo, não o rótulo. Confira em Configurações do ServiceDesk › Campos customizados

ServiceDesk na API v1

Listar chamados

Ver um chamado

Abrir um chamado

Comentar

Mudar de fase

Listar fases

Catálogo de serviços

Receitas

Solução de problemas

Parâmetro	Valores
`ticketType`	`INCIDENT`, `SERVICE_REQUEST`, `CHANGE` ou `PROBLEM`. Omitido = todos os tipos
`limit`, `cursor`	Paginação