Skip to main content

Python

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

​
Requisitos

  • Python 3.10 ou superior
  • Dependências instaladas automaticamente: httpx e pydantic

​
Instalação

pip install beehivehub-python-sdk

​
Autenticação

Inicialize o SDK com a sua SECRET_KEY: 
import os
from beehivehub import create_beehivehub_client

beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])

​
Ambiente Sandbox

Se quiser usar o ambiente de testes: 
import os
from beehivehub import create_beehivehub_client

beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"], environment="sandbox")

​
Primeiro uso

Exemplo de criação de uma transação Pix: 
import os
from beehivehub import create_beehivehub_client

beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])

transaction = 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",
    },
})

​
Recursos disponíveis

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

​
Transações

​
Criar transação

transaction = 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

transactions = beehive.transactions.list({
    "status": "paid",
    "paymentMethods": "pix",
})

​
Buscar transação por ID

transaction = beehive.transactions.get(123456)

​
Reembolsar transação

full_refund = beehive.transactions.refund(123456)

partial_refund = beehive.transactions.refund(123456, 3000)

​
Atualizar status de entrega

delivery = beehive.transactions.update_delivery(123456, {
    "status": "in_transit",
    "trackingCode": "BR123456789",
})

​
Clientes

​
Criar cliente

customer = 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. 
customers = beehive.customers.list({
    "email": "cliente@example.com",
})

​
Buscar cliente por ID

customer = beehive.customers.get(123456)

​
Transferências

​
Criar transferência

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

​
Criar transferência com conta bancária

transfer = 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

transfer = beehive.transfers.get(123456)

​
Saldo

​
Consultar saldo

balance = beehive.balance.get()

print(f"Available: BRL {balance['amount'] / 100}")
print(f"Recipient ID: {balance['recipientId']}")

​
Recebedores

​
Criar recebedor

recipient = 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

recipients = beehive.recipients.list()

​
Buscar recebedor por ID

recipient = beehive.recipients.get(916)

​
Atualizar recebedor

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

​
Contas bancárias

​
Adicionar conta bancária a um recebedor

bank_account = beehive.bank_accounts.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

accounts = beehive.bank_accounts.list(916)

​
Empresa

​
Consultar dados da empresa

company = beehive.company.get()

​
Atualizar dados da empresa

updated = 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. 
payment_link = beehive.payment_links.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,
        },
    },
})

# payment_link["url"] já vem montada
A API não aceita filtros por query parameters nesse recurso. A listagem retorna todos os links da empresa. 
payment_links = beehive.payment_links.list()

payment_link = beehive.payment_links.get(247)
A atualização aceita payload parcial, ou seja, você pode enviar apenas os campos que deseja alterar. 
updated = beehive.payment_links.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,
        },
    },
})

beehive.payment_links.delete(247)

​
Tratamento de erros

O SDK expõe classes específicas para tratamento de erro:
  • BeehiveHubAPIError
  • BeehiveHubAuthenticationError
  • BeehiveHubValidationError
  • BeehiveHubNotFoundError
  • BeehiveHubRateLimitError
  • BeehiveHubNetworkError
Exemplo: 
import os
from beehivehub import (
    create_beehivehub_client,
    BeehiveHubAPIError,
    BeehiveHubAuthenticationError,
    BeehiveHubValidationError,
)

beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])

try:
    transaction = beehive.transactions.create({
        "amount": 10000,
        "paymentMethod": "pix",
        "customer": {
            "name": "João Silva",
            "email": "joao@example.com",
            "document": {
                "type": "cpf",
                "number": "12345678900",
            },
            "phone": "11999999999",
        },
    })
    print("Transaction created:", transaction)
except BeehiveHubAuthenticationError as e:
    print(f"Invalid API key: {e}")
except BeehiveHubValidationError as e:
    print(f"Validation error: {e}")
except BeehiveHubAPIError as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
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
reais = 100.0
cents = 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.py
import os
from dotenv import load_dotenv
from beehivehub import create_beehivehub_client

load_dotenv()

beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])