integrax-sdk

SDK oficial da Integrax para Node.js e TypeScript — SMS, RCS, OTP e consultas via API REST.

• Zero dependências (usa fetch nativo)
• TypeScript first — tipos completos pra todas as respostas
• CJS + ESM

Instalação

npm install integrax-sdk

Quick start

import { Integrax } from "integrax-sdk";

const ix = new Integrax("seu-token-aqui");

// Enviar SMS
const res = await ix.sms.send(["5511999999999"], "Pedido #4821 confirmado ✓");

console.log(res.data[0].messageId); // "82816396"

Configuração

// Apenas token (usa defaults)
const ix = new Integrax("seu-token");

// Com opções
const ix = new Integrax({
  token: "seu-token",
  baseUrl: "https://sms.aresfun.com", // padrão
  timeout: 15000, // padrão: 30000ms
});

SMS

// Envio simples (usa shortcode padrão da conta)
const res = await ix.sms.send(
  ["5511999999999", "5521888888888"],
  "Sua mensagem aqui",
);

// Com shortcode customizado
const res = await ix.sms.send(
  ["5511999999999"],
  "Sua mensagem aqui",
  { from: "29094" },
);

// res.code === "SMS_SENT"
// res.data[0].status === "SENT_TO_OPERATOR"
// res.data[0].messageId === "82816396"

DLR (webhook)

Configure seu webhook para receber o status de entrega:

// Payload recebido no seu endpoint
interface DlrPayload {
  message_id: string;
  status: "DELIVRD" | "EXPIRED" | "REJECTD" | "UNDELIV";
  number: string;
}

OTP

Duas chamadas: enviar código e verificar.

// 1. Envio mínimo (usa todos os defaults: 6 dígitos numéricos, expira em 10min)
await ix.otp.send("5511999999999");

// 1b. Personalizado
await ix.otp.send("5511999999999", {
  message_default: "Use [code] pra confirmar sua conta", // padrão: "Seu código: [code]"
  from: "29094",        // se omitido, usa o padrão da conta
  qtd_digits: 5,        // padrão: 6
  with_text: true,      // alfanumérico (padrão: false = só números)
  expires_in: 5,        // minutos (padrão: 10)
});

// 2. Verificar código digitado pelo usuário
const verify = await ix.otp.verify("1MP5L", "5511999999999");

if (verify.status === "verified") {
  // código válido
}

RCS

BASIC (só texto)

await ix.rcs.send({
  to: ["5511999999999"],
  message: "Olá! Mensagem RCS básica.",
  from: "IntegraX",
  rcsType: "BASIC",
});

RICH (card com mídia e botões)

await ix.rcs.send({
  to: ["5511999999999"],
  message: "Confira nossa oferta!",
  from: "IntegraX",
  rcsMessage: {
    card: {
      title: "Black Friday",
      description: "Até 60% OFF em todos os produtos.",
      media: {
        file: { url: "https://exemplo.com/banner.png" },
        height: "MEDIUM",
      },
      suggestions: [
        {
          type: "OPEN_URL",
          text: "Ver ofertas",
          url: "https://exemplo.com/ofertas",
          postbackData: "click_ofertas",
        },
      ],
    },
  },
});

Créditos

const balance = await ix.credits.balance();
console.log(balance);

Consultas

Por CPF

const res = await ix.consult.cpf(["00000000001"], {
  showPhoneValid: true,
  showRestrictions: true,
});

Por telefone

const res = await ix.consult.phone(["551199999999"]);

Telefone premium (dados enriquecidos)

const res = await ix.consult.phonePremium(["551199999999"]);

Números internacionais

• Para números de outros países, insira + na frente do número (ex: +34992000000).
• Para envios internacionais, é necessário solicitar a ativação da rota através do suporte.
• Alguns países permitem from personalizado. Se permitido, basta informar o from no payload.

Tratamento de erros

import { Integrax, IntegraxError } from "integrax-sdk";

try {
  await ix.sms.send(["551100000000"], "teste");
} catch (err) {
  if (err instanceof IntegraxError) {
    console.error(err.status); // HTTP status (ex: 401, 422)
    console.error(err.code); // código da API
    console.error(err.body); // corpo completo da resposta
  }
}

Timeout também lança IntegraxError com status: 0 e code: "TIMEOUT".

Build

npm run build     # gera dist/ (CJS + ESM + .d.ts)
npm run typecheck # verifica tipos sem emitir

Licença

MIT