Skip to main content

Node.js

SDK oficial para integração com a API do Beehive Hub. Aceite pagamentos de forma simples e rápida.

​
O que é o SDK Node.js?

O SDK oficial Node.js da BeehiveHub é uma biblioteca que facilita a integração com a nossa API em aplicações backend. Em vez de montar manualmente chamadas HTTP, headers de autenticação, tratamento de erros e estrutura de requisições, você pode usar métodos prontos para criar transações, consultar clientes, gerar links de pagamento, fazer transferências e acessar outros recursos da plataforma de forma mais simples.

​
Por que usar o SDK?

O SDK foi criado para tornar a integração mais rápida, organizada e segura para quem desenvolve com Node.js. Ao utilizar o SDK, você reduz a complexidade da implementação porque:
  • não precisa montar requisições manualmente para cada endpoint;
  • centraliza a autenticação com a sua SECRET_KEY;
  • trabalha com métodos mais diretos e fáceis de manter;
  • reduz a chance de erro na integração;
  • acelera a implementação dos recursos mais comuns da API.
Ele é especialmente útil para empresas e desenvolvedores que querem integrar pagamentos no backend com mais agilidade, sem precisar lidar diretamente com toda a estrutura das chamadas HTTP.

​
Quando faz sentido usar o SDK?

O SDK é indicado quando você possui uma aplicação em Node.js e quer integrar a BeehiveHub no seu servidor, API própria, painel administrativo, backoffice ou backend de e-commerce. Exemplos de uso:
  • criação de transações Pix, boleto e cartão;
  • consulta de transações e clientes;
  • criação de recebedores e transferências;
  • geração de links de pagamento;
  • automações internas do seu sistema financeiro.
Recomendamos o uso do SDK principalmente para integrações server-side. Não utilize sua SECRET_KEY no front-end.

​
Onde utilizar os comandos?

Os comandos mostrados nesta página devem ser usados em ambientes diferentes, dependendo do objetivo.

​
Comandos de instalação

Os comandos como: 
npm install @paybeehive/beehivehub-nodejs-sdk

​
Autenticação

Inicialize o SDK com a sua SECRET_KEY: 
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";

const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);

​
Ambiente Sandbox

Se quiser usar o ambiente de testes: 
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";

const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!, {
  environment: "sandbox",
});

​
Primeiro uso

Exemplo de criação de uma transação Pix: 
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";

const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);

async function criarTransacao() {
  const response = await beehive.transactions.create({
    amount: 15990,
    paymentMethod: "pix",
    customer: {
      name: "Ana Souza",
      email: "ana.souza@email.com",
      document: {
        type: "cpf",
        number: "00000000191",
      },
      phone: "11999999999",
    },
    items: [
      {
        title: "Pedido #1001",
        unitPrice: 15990,
        quantity: 1,
        tangible: true,
      },
    ],
    postbackUrl: "https://seusite.com/webhook",
    metadata: {
      orderId: "1001",
    },
  });

  return response;
}

​
Recursos disponíveis

O SDK possui métodos para os principais recursos da API:
  • transactions
  • customers
  • transfers
  • balance
  • recipients
  • bankAccounts
  • company
  • paymentLinks

​
Transações

​
Criar transação

const transaction = await beehive.transactions.create({
  amount: 8900,
  paymentMethod: "pix",
  customer: {
    name: "Carlos Lima",
    email: "carlos@email.com",
    document: {
      type: "cpf",
      number: "00000000191",
    },
    phone: "11988888888",
  },
  items: [
    {
      title: "Produto teste",
      unitPrice: 8900,
      quantity: 1,
      tangible: true,
    },
  ],
});

​
Listar transações

const transactions = await beehive.transactions.list({
  limit: 50,
  offset: 0,
  createdFrom: "2026-01-01T00:00:00",
})

​
Buscar transação por ID

const transaction = await beehive.transactions.get(123456);

​
Reembolsar transação

const fullRefund = await beehive.transactions.refund(123456);

const partialRefund = await beehive.transactions.refund(123456, 3000);

​
Atualizar status de entrega

const delivery = await beehive.transactions.updateDelivery(123456, {
  status: "in_transit",
  trackingCode: "BR123456789",
});

​
Clientes

​
Criar cliente

const customer = await beehive.customers.create({
  name: "Mariana Costa",
  email: "mariana@email.com",
  document: {
    type: "cpf",
    number: "98765432100",
  },
  phone: "11977777777",
  address: {
    street: "Rua Exemplo",
    streetNumber: "200",
    complement: "Sala 3",
    neighborhood: "Centro",
    zipCode: "01001000",
    city: "São Paulo",
    state: "SP",
    country: "br",
  },
});

​
Listar clientes

O parâmetro email é obrigatório nessa listagem. A API não utiliza paginação convencional para este recurso. 
const customers = await beehive.customers.list({
  email: "cliente@example.com",
});

​
Buscar cliente por ID

const customers = await beehive.customers.list({
  email: "cliente@example.com",
});

​
Transferências

​
Criar transferência

const transfer = await beehive.transfers.create({
  amount: 50000,
  recipientId: 916,
});

​
Criar transferência com conta bancária

const transferWithAccount = await beehive.transfers.create({
  amount: 50000,
  recipientId: 916,
  bankAccount: {
    bankCode: "001",
    agencyNumber: "1234",
    accountNumber: "12345",
    accountDigit: "6",
    type: "conta_corrente",
    legalName: "Destinatário Teste",
    documentNumber: "12345678900",
    documentType: "cpf",
  },
});

​
Buscar transferência por ID

const transfer = await beehive.transfers.get(123456);

​
Saldo

​
Consultar saldo

const balance = await beehive.balance.get();

console.log(`Available: BRL ${balance.amount / 100}`);
console.log(`Recipient ID: ${balance.recipientId}`);

​
Recebedores

​
Criar recebedor

const recipient = await beehive.recipients.create({
  legalName: "Recebedor Teste Ltda",
  document: {
    type: "cnpj",
    number: "58593776000142",
  },
  transferSettings: {
    transferEnabled: true,
    automaticAnticipationEnabled: false,
    anticipatableVolumePercentage: 100,
  },
  bankAccount: {
    bankCode: "001",
    agencyNumber: "1234",
    accountNumber: "12345",
    accountDigit: "6",
    type: "conta_corrente",
    legalName: "Recebedor Teste Ltda",
    documentNumber: "58593776000142",
    documentType: "cnpj",
  },
});

​
Listar recebedores

const recipients = await beehive.recipients.list();

​
Buscar recebedor por ID

const recipient = await beehive.recipients.get(916);

​
Atualizar recebedor

const updated = await beehive.recipients.update(916, {
  legalName: "Beehive Sandbox",
});

​
Contas bancárias

​
Adicionar conta bancária a um recebedor

const bankAccount = await beehive.bankAccounts.create(916, {
  bankCode: "341",
  agencyNumber: "9876",
  accountNumber: "54321",
  accountDigit: "0",
  type: "conta_poupanca",
  legalName: "Empresa Teste Ltda",
  documentNumber: "60572883000136",
  documentType: "cnpj",
});

​
Listar contas bancárias

const accounts = await beehive.bankAccounts.list(916);

​
Empresa

​
Consultar dados da empresa

const company = await beehive.company.get();

​
Atualizar dados da empresa

const updated = await beehive.company.update({
  invoiceDescriptor: "Beehive Hub",
  details: {
    averageRevenue: 10000,
    averageTicket: 100.5,
    physicalProducts: true,
    productsDescription: "Produtos físicos",
    siteUrl: "https://www.meusite.com.br",
    phone: "11999999999",
    email: "contato@meusite.com.br",
  },
});
O SDK adiciona a propriedade url nas respostas de criação, consulta, listagem e atualização quando existe um alias.
  • Produção: https://link.conta.paybeehive.com.br/{alias}
  • Sandbox: https://link.sandbox.hopysplit.com.br/{alias}
Se alias não for enviado, o SDK gera automaticamente um código alfanumérico de 10 caracteres. 
const paymentLink = await beehive.paymentLinks.create({
  title: "novo link alterado",
  alias: "alias_alterado",
  amount: 1000,
  settings: {
    defaultPaymentMethod: "credit_card",
    requestAddress: true,
    requestPhone: true,
    traceable: true,
    boleto: {
      enabled: true,
      expiresInDays: 0,
    },
    pix: {
      enabled: false,
      expiresInDays: 0,
    },
    card: {
      enabled: false,
      freeInstallments: 1,
      maxInstallments: 12,
    },
  },
});

// paymentLink.url já vem montada
A API não aceita filtros por query parameters nesse recurso. A listagem retorna todos os links da empresa. 
const paymentLinks = await beehive.paymentLinks.list();

const paymentLink = await beehive.paymentLinks.get(247);
A atualização aceita payload parcial, ou seja, você pode enviar apenas os campos que deseja alterar. 
const updated = await beehive.paymentLinks.update(247, {
  title: "novo link alterado",
  alias: "alias_alterado",
  amount: 1000,
  settings: {
    defaultPaymentMethod: "credit_card",
    requestAddress: true,
    requestPhone: true,
    traceable: true,
    boleto: {
      enabled: true,
      expiresInDays: 0,
    },
    pix: {
      enabled: false,
      expiresInDays: 0,
    },
    card: {
      enabled: false,
      freeInstallments: 1,
      maxInstallments: 12,
    },
  },
});

await beehive.paymentLinks.delete(247);

​
Tratamento de erros

O SDK expõe classes específicas para tratamento de erro:
  • BeehiveHubAPIError
  • BeehiveHubAuthenticationError
  • BeehiveHubValidationError
  • BeehiveHubNotFoundError
  • BeehiveHubRateLimitError
  • BeehiveHubNetworkError
Exemplo: 
import BeehiveHub, {
  BeehiveHubAPIError,
  BeehiveHubAuthenticationError,
  BeehiveHubValidationError,
} from "@paybeehive/beehivehub-nodejs-sdk";

const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);

try {
  const transaction = await beehive.transactions.create({
    amount: 10000,
    paymentMethod: "pix",
    customer: {
      name: "João Silva",
      email: "joao@example.com",
      document: {
        type: "cpf",
        number: "12345678900",
      },
      phone: "11999999999",
    },
  });

  console.log("Transaction created:", transaction);
} catch (error) {
  if (error instanceof BeehiveHubAuthenticationError) {
    console.error("Invalid API key:", error.message);
  } else if (error instanceof BeehiveHubValidationError) {
    console.error("Validation error:", error.message);
  } else if (error instanceof BeehiveHubAPIError) {
    console.error("API error:", error.message);
  } else {
    console.error("Unexpected error:", error);
  }
}

​
Valores em centavos

Todos os valores monetários enviados para a API devem ser informados em centavos. 
// R$ 100,00
amount: 10000;

// R$ 1,50
amount: 150;

// Convertendo reais para centavos
const reais = 100.0;
const cents = Math.round(reais * 100);

​
Boas práticas de segurança

  • Nunca exponha sua SECRET_KEY
  • Não gere card_hash no backend
  • Valide os dados antes de enviar para a API
  • Use HTTPS
  • Implemente webhooks para acompanhar mudanças de status
// .env
BEEHIVE_SECRET_KEY=your_secret_key_here

// app.ts
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";
import dotenv from "dotenv";

dotenv.config();

const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);

​
Testes

npm test

npm run test:corerage