@steel-so/sdk | Desenvolvedores Steel

@steel-so/sdk

O SDK TypeScript da API pública v1. Instale, crie o cliente, faça chamadas tipadas, percorra páginas, trate erros sem exceção, faça o login por dispositivo e confira webhooks.

Nesta página

O @steel-so/sdk é o SDK TypeScript da API pública v1. Os tipos são gerados do documento OpenAPI da v1 (/dev/api/v1/openapi.json), então o editor completa rotas, parâmetros e campos de resposta. É o mesmo SDK que o Steel CLI usa.

O código fica em steel-so/steel-cli, na pasta packages/sdk. A versão atual é a 0.1.0.

Instale

npm install @steel-so/sdk
# ou: pnpm add @steel-so/sdk  /  yarn add @steel-so/sdk

Node.js 22.12 ou mais novo. O pacote é ESM.
Só no servidor. O token dá acesso ao workspace em seu nome; não coloque no navegador nem num aplicativo móvel. A API também não libera chamadas de outros domínios pelo navegador (CORS).
A única dependência é o openapi-fetch.

Crie o cliente

Você precisa de um token pessoal (stl_pat_…), criado em Configurações › Segurança › Tokens de API ou pelo steel login. Veja Token pessoal.

import { createSteelClient } from '@steel-so/sdk'

const steel = createSteelClient({
  baseUrl: 'https://homologacao.stratustelecom.com.br',
  token: process.env.STEEL_TOKEN,
})

const me = await steel.me()
if (!me.ok) throw new Error(`${me.error.status} ${me.error.code}`)
console.log(me.data.user.name, me.data.workspace.slug, me.data.scopes)

Opção	Padrão	Para quê
`baseUrl`	(obrigatória)	O endereço do Steel, sem `/api`
`token`	nenhum	O token pessoal. Só o login por dispositivo funciona sem ele
`timeoutMs`	`30000`	Tempo máximo de cada requisição, em milissegundos
`fetch`	`globalThis.fetch`	Outra implementação de `fetch` (testes, proxy)
`userAgent`	nenhum

type SteelResult<T> =
  | { ok: true; status: number; data: T }
  | { ok: false; error: SteelError }

interface SteelError {
  status: number             // status HTTP, ou 0 quando não houve resposta
  code: string               // error.code do Steel, ou NETWORK_ERROR, TIMEOUT, ABORTED
  message?: string           // mensagem para pessoas (pt-BR); pode mudar
  details?: unknown          // em VALIDATION_ERROR, os problemas de cada campo
  retryAfterSeconds?: number // do cabeçalho Retry-After, quando vem
}

const created = await steel.crm.leads.create({
  name: 'Ana Souza',
  emails: ['ana@exemplo.com'],
  source: 'site',
})

if (!created.ok) {
  switch (created.error.code) {
    case 'CRM_LEAD_DUPLICATE':
      break // já existe um lead em aberto com esse e-mail ou telefone
    case 'API_TOKEN_SCOPE_REQUIRED':
      throw new Error('O token é só leitura: crie um com api:write')
    case 'RATE_LIMITED':
      await new Promise((r) => setTimeout(r, (created.error.retryAfterSeconds ?? 60) * 1000))
      break
    default:
      throw new Error(`${created.error.status} ${created.error.code}: ${created.error.message ?? ''}`)
  }
} else {
  console.log(created.status, created.data.id, created.data.score, created.data.ownerId)
}

Status	Código	O que significa
`0`	`NETWORK_ERROR`, `TIMEOUT`, `ABORTED`	Não houve resposta: rede, tempo esgotado ou `AbortSignal`
`401`	`UNAUTHORIZED`	Token ausente, inválido, vencido ou revogado, ou o dono saiu do workspace
`403`	`API_TOKEN_SCOPE_REQUIRED`	Escrita com um token só de leitura
`403`	`API_TOKEN_MODULE_NOT_ALLOWED`	Rota de um módulo que o token não tem, ou que foi desabilitado
`403`	`FORBIDDEN`	O seu papel não permite, ou falta aceitar os termos no Steel
`404`	`RESOURCE_NOT_FOUND`, `SD_TICKET_NOT_FOUND`…	O registro não existe ou você não o vê
`409`	`CRM_LEAD_DUPLICATE`	Já existe um lead em aberto com o mesmo e-mail ou telefone
`422`	`VALIDATION_ERROR`	Corpo ou parâmetro inválido; veja `details`
`429`	`RATE_LIMITED`	Limite de requisições; espere `retryAfterSeconds`

const queue = await steel.servicedesk.tickets.list({
  assigneeId: ['me'],
  status: ['NEW', 'IN_PROGRESS', 'WAITING'],
  limit: 50,
})

const ticket = await steel.servicedesk.tickets.create({
  type: 'INCIDENT',
  title: 'VPN fora do ar',
  description: '<p>Usuários da filial sem acesso desde 9h.</p>',
})
if (ticket.ok) {
  await steel.servicedesk.tickets.comment(ticket.data.id, {
    body: 'Já estamos olhando',
    visibility: 'INTERNAL',
  })
}

await steel.servicedesk.tickets.get('42')            // pelo id ou pelo número
await steel.servicedesk.tickets.move('42', { phaseId: '<id-da-fase>', solution: 'Link restabelecido' })
await steel.servicedesk.catalog({ ticketType: 'SERVICE_REQUEST' })

await steel.crm.leads.list({ stage: 'QUALIFIED' })
await steel.crm.leads.create({ name: 'Ana Souza', emails: ['ana@exemplo.com'], source: 'site' })

import { readFile } from 'node:fs/promises'
const report = await steel.crm.leads.import(await readFile('leads.csv', 'utf8'), { source: 'Feira' })
if (report.ok) console.log(report.data.created, report.data.skipped, report.data.errors)

const pipelines = await steel.crm.pipelines()
await steel.crm.opportunities.list({ pipelineId: '<id-do-funil>' })
await steel.crm.opportunities.move('<id-da-oportunidade>', { stageId: '<id-da-etapa>' })

const templates = await steel.whatsapp.templates({ status: 'APPROVED' })

const sent = await steel.whatsapp.sendTemplate({
  to: '+5511999990000',
  templateName: 'boas_vindas',
  language: 'pt_BR',
  components: [{ type: 'body', parameters: [{ type: 'text', text: 'Ana' }] }],
})
if (sent.ok) console.log(sent.data.id, sent.data.status) // PENDING, SENT…

await steel.whatsapp.broadcast('<id-do-disparo>')

import { collectAll } from '@steel-so/sdk'

const all = await collectAll((cursor) =>
  steel.crm.leads.list({ limit: 100, cursor }),
)
if (all.ok) console.log(`${all.data.items.length} leads`)

let cursor: string | undefined
do {
  const page = await steel.servicedesk.tickets.list({ limit: 100, cursor })
  if (!page.ok) throw new Error(page.error.code)
  for (const ticket of page.data.items) console.log(ticket.code, ticket.title)
  cursor = page.data.nextCursor ?? undefined
} while (cursor)

const { data, error, response } = await steel.api.GET('/api/v1/crm/leads', {
  params: { query: { limit: 10, stage: 'RECEIVED' } },
})
if (data) console.log(data.data?.items.length)
else console.error(response.status, error)

import { createSteelClient, waitForDeviceToken } from '@steel-so/sdk'
import { hostname } from 'node:os'

const steel = createSteelClient({ baseUrl: 'https://homologacao.stratustelecom.com.br' })

const started = await steel.auth.startDevice({
  clientName: 'meu-script/1.0',
  deviceName: hostname(),
})
if (!started.ok) throw new Error(started.error.code)

console.log(`Abra ${started.data.verificationUriComplete} e confirme o código ${started.data.userCode}`)

const abort = new AbortController()
process.once('SIGINT', () => abort.abort())

const outcome = await waitForDeviceToken(steel, started.data, { signal: abort.signal })
switch (outcome.status) {
  case 'approved':
    // outcome.token: { token, tokenId, expiresAt, workspace, scopes, modules }
    console.log(`Conectado a ${outcome.token.workspace.name}`)
    break
  case 'expired':   // passaram os 10 minutos
  case 'denied':    // o usuário clicou em Recusar
  case 'cancelled': // o AbortSignal disparou
    process.exitCode = 3
    break
  case 'error':
    throw new Error(outcome.error.code)
}

// Next.js: app/webhooks/steel/route.ts
import { verifySignature } from '@steel-so/sdk'

export async function POST(request: Request) {
  const rawBody = await request.text()
  const valid = verifySignature(
    process.env.STEEL_WEBHOOK_SECRET ?? '',
    request.headers.get('steel-signature'),
    request.headers.get('steel-webhook-timestamp'),
    rawBody,
  )
  if (!valid) return new Response('assinatura inválida', { status: 401 })

  const event = JSON.parse(rawBody) as { id: string; type: string; createdAt: string; data: unknown }
  // Use event.id (o mesmo Steel-Webhook-Id em todas as tentativas) para não processar duas vezes.
  return new Response(null, { status: 204 })
}

// Express: o corpo precisa chegar cru, sem express.json() antes
import express from 'express'
import { verifySignature } from '@steel-so/sdk'

const app = express()
app.post('/webhooks/steel', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  const ok = verifySignature(
    process.env.STEEL_WEBHOOK_SECRET ?? '',
    req.get('steel-signature'),
    req.get('steel-webhook-timestamp'),
    rawBody,
  )
  if (!ok) return res.status(401).send('assinatura inválida')
  res.sendStatus(204)
})

import { signPayload, WEBHOOK_HEADERS } from '@steel-so/sdk'

const body = JSON.stringify({ id: 'evt_teste', type: 'crm.lead.created', createdAt: new Date().toISOString(), workspaceId: 'ws', data: {} })
const timestamp = Math.floor(Date.now() / 1000)
await fetch('http://localhost:3001/webhooks/steel', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    [WEBHOOK_HEADERS.id]: 'evt_teste',
    [WEBHOOK_HEADERS.timestamp]: String(timestamp),
    [WEBHOOK_HEADERS.signature]: signPayload('whsec_teste', timestamp, body),
  },
  body,
})

Método	Faz
`events()`	O catálogo de eventos que o token alcança
`listEndpoints()`, `createEndpoint(body)`, `updateEndpoint(id, body)`, `deleteEndpoint(id)`	Endpoints. O segredo só vem na resposta de `createEndpoint`
`testEndpoint(id)`	Envia um `steel.ping` e devolve a entrega
`listDeliveries({ endpointId, status, limit, cursor })`, `retryDelivery(id)`	O log de entregas (30 dias) e o reenvio
`trigger({ type, endpointId })`	Um evento de teste com os dados de exemplo
`listen({ events, signal })`	A escuta em tempo real (Server-Sent Events)

const opened = await steel.webhooks.listen({ events: ['crm.lead.created'] })
if (!opened.ok) throw new Error(opened.error.code) // 401, 403, tipo fora do catálogo

for await (const message of opened.data) {
  if (message.type === 'ready') console.log('segredo da escuta:', message.ready.secret)
  if (message.type === 'webhook') console.log(message.event?.type, message.frame.id)
  if (message.type === 'disconnected') console.log('fim:', message.reason) // end, idle, aborted, network
}

Sintoma	O que fazer
Erro de tipo em `process.env.STEEL_TOKEN`	`token` aceita `undefined`, mas `verifySignature` exige `string`: passe `process.env.STEEL_WEBHOOK_SECRET ?? ''`
`UNAUTHORIZED` em toda chamada	O token venceu, foi revogado ou é de outro ambiente. Confira com `steel.me()`
`API_TOKEN_MODULE_NOT_ALLOWED`	Crie um token que inclua o módulo da rota
`verifySignature` sempre `false`	O corpo foi lido como JSON e serializado de novo, o segredo é de outro endpoint (ou da escuta) ou o relógio do servidor está fora de hora
`TIMEOUT` em chamadas longas	Aumente `timeoutMs` no `createSteelClient`
`data` vem `undefined` em `steel.api.GET`	Houve erro: leia `error` e `response.status`, ou use os atalhos, que já devolvem `SteelResult`

@steel-so/sdk

Instale

Crie o cliente

O resultado: sem exceção

Atalhos por módulo

ServiceDesk

CRM

Comunicação (WhatsApp)

Percorra todas as páginas

Qualquer rota, tipada: `steel.api`

Confira a assinatura de um webhook

Endpoints, entregas e a escuta

O que mais o pacote exporta

Limites e versões

Solução de problemas

Instale

Crie o cliente

O resultado: sem exceção

Atalhos por módulo

ServiceDesk

CRM

Comunicação (WhatsApp)

Percorra todas as páginas

Qualquer rota, tipada: steel.api

Login por dispositivo

Confira a assinatura de um webhook

Endpoints, entregas e a escuta

O que mais o pacote exporta

Limites e versões

Solução de problemas

Qualquer rota, tipada: `steel.api`