Skip to main content
O cliente sparkcrm inclui comportamentos de produção herdados do gerador Stainless. Esta página resume o que importa ao integrar o Spark de forma resiliente.

​
Erros HTTP

Falhas de rede ou respostas 4xx / 5xx lançam subclasses de SparkCRM.APIError:
StatusClasse
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
422UnprocessableEntityError
429RateLimitError
≥ 500InternalServerError
Sem resposta HTTPAPIConnectionError
TimeoutAPIConnectionTimeoutError
import SparkCRM from "sparkcrm";

try {
  await client.entrypoints.list();
} catch (err) {
  if (err instanceof SparkCRM.RateLimitError) {
    // aguardar e tentar de novo, ou reduzir throughput
  } else if (err instanceof SparkCRM.APIError) {
    console.error(err.status, err.message);
  } else {
    throw err;
  }
}
Mensagens de validação da API (por exemplo variáveis de template faltando) costumam vir em 400 com texto descritivo no corpo.

​
Retentativas

Por padrão o cliente repete até 2 vezes com backoff exponencial em:
  • erros de conexão;
  • 408, 409, 429;
  • 5xx.
Desligar ou ajustar globalmente: 
const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY,
  maxRetries: 0,
});
Ou por requisição: 
await client.entrypoints.list({ maxRetries: 5 });

​
Timeouts

Padrão: 60 segundos por tentativa (com retentativas o tempo total pode ser maior). 
const client = new SparkCRM({
  timeout: 20_000,
});

await client.messaging.chats.sendMessage(chatId, { text: "ok" }, {
  timeout: 5_000,
});

​
Resposta HTTP bruta

Métodos retornam APIPromise<T>. Para acessar cabeçalhos sem consumir o body: 
const response = await client.entrypoints.list().asResponse();
console.log(response.status, response.headers.get("x-request-id"));
Para dados parseados e Response: 
const { data, response } = await client.entrypoints.list().withResponse();

​
Logging

Nível via SPARK_CRM_LOG ou logLevel no construtor: debug, info, warn, error, off (padrão warn). Em debug, requisições e respostas são logadas (cuidado com dados sensíveis em produção). Logger customizado (Pino, Winston, etc.): 
import SparkCRM from "sparkcrm";
import pino from "pino";

const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY,
  logger: pino().child({ name: "spark" }),
  logLevel: "info",
});

​
Fetch e proxy

Passe fetch alternativo ou fetchOptions (por exemplo dispatcher do Undici no Node para proxy corporativo). Exemplos no README do repositório.

​
Parâmetros e endpoints não documentados

O SDK não valida em runtime campos extras — você pode enviar opções ainda não refletidas nos tipos: 
await client.entrypoints.list({
  // @ts-expect-error parâmetro novo na API
  includeInactive: true,
});
Para rotas sem método dedicado: 
await client.post("/v1/messaging/chats/{chatId}/templates", {
  body: { templateId: "…", commonVariables: { var1: "x" } },
});

​
Versionamento

O pacote segue SemVer. Mudanças só de tipos podem sair em versão minor sem quebrar runtime. Acompanhe releases no npm e issues no GitHub.

​
Leitura relacionada