Beehive Hub Python SDK

Official SDK for integrating with the Beehive Hub API. Accept payments simply and quickly.

Table of Contents

• Requirements
• Installation
• Quick Start
• Authentication
• Resources
  • Transactions
  • Customers
  • Transfers
  • Balance
  • Recipients
  • Bank Accounts
  • Company
  • Payment Links
• Error Handling
• Values in Cents
• Security Best Practices
• Type Safety
• Development
• Support
• License

Requirements

• Python >= 3.10

Installation

pip install beehivehub-python-sdk

Dependencies (installed automatically):

• httpx - HTTP client
• pydantic - Data validation and models

Quick Start

from beehivehub import create_beehivehub_client

beehive = create_beehivehub_client("your_secret_key")

transaction = beehive.transactions.create({
    "amount": 10000,  # BRL 100.00 in cents
    "paymentMethod": "pix",
    "customer": {
        "name": "João Silva",
        "email": "joao@example.com",
        "document": {"type": "cpf", "number": "00000000191"},
        "phone": "11999999999",
    },
    "items": [
        {"title": "Produto Teste", "unitPrice": 10000, "quantity": 1, "tangible": True}
    ],
    "postbackUrl": "https://example.com/webhook",
})

print("Transaction created:", transaction)

Authentication

The SDK uses Basic Authentication. Provide your SECRET_KEY when initializing.

Getting your credentials

1. Access the Beehive Hub dashboard
2. Navigate to Settings > API Credentials
3. Copy your SECRET_KEY

beehive = create_beehivehub_client("your_secret_key_here")

Sandbox environment

beehive = create_beehivehub_client("your_secret_key", environment="sandbox")

Important: Never expose your secret key in client-side code or public repositories. Use environment variables:

import os

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

Resources

Transactions

Create a transaction

transaction = beehive.transactions.create({
    "amount": 10000,
    "paymentMethod": "pix",
    "customer": {
        "name": "João Silva",
        "email": "joao@example.com",
        "document": {"type": "cpf", "number": "00000000191"},
        "phone": "11999999999",
    },
    "items": [
        {"title": "Produto Teste", "unitPrice": 10000, "quantity": 1, "tangible": True}
    ],
    "postbackUrl": "https://example.com/webhook",
    "metadata": {"orderId": "1234567890"},
})

List transactions

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

Get a transaction

transaction = beehive.transactions.get(123456)

Refund a transaction

# Full refund
refund = beehive.transactions.refund(123456)

# Partial refund
partial_refund = beehive.transactions.refund(123456, 5000)

Update delivery status

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

Customers

Create a customer

customer = beehive.customers.create({
    "name": "Maria Santos",
    "email": "maria@example.com",
    "document": {"type": "cpf", "number": "98765432100"},
    "phone": "11988888888",
    "address": {
        "street": "Rua Teste",
        "streetNumber": "456",
        "complement": "Apto 101",
        "neighborhood": "Jardins",
        "zipCode": "01234567",
        "city": "São Paulo",
        "state": "SP",
        "country": "br",
    },
})

List customers

O parâmetro email é obrigatório. A API não aceita parâmetros de paginação convencionais.

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

Get a customer

customer = beehive.customers.get(123456)

Transfers

Create a transfer

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

# With optional bank account
transfer_with_account = 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",
    },
})

Get a transfer

transfer = beehive.transfers.get(123456)

Balance

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

Recipients

Create a recipient

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

List recipients

recipients = beehive.recipients.list()

Get a recipient

recipient = beehive.recipients.get(916)

Update a recipient

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

Bank Accounts

Add a bank account

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

List bank accounts

accounts = beehive.bank_accounts.list(916)

Company

Get company data

company = beehive.company.get()

Update company data

updated = beehive.company.update({
    "invoiceDescriptor": "Beehive Hub",
    "details": {
        "averageRevenue": 10000,
        "averageTicket": 100.50,
        "physicalProducts": True,
        "productsDescription": "Produtos físicos",
        "siteUrl": "https://www.meusite.com.br",
        "phone": "11999999999",
        "email": "contato@meusite.com.br",
    },
})

Payment Links

O SDK adiciona url às respostas (create, get, list, update) quando há alias:

• Produção: https://link.conta.paybeehive.com.br/{alias}
• Sandbox: https://link.sandbox.hopysplit.com.br/{alias}

Create a payment link

Create e update aceitam payloads parciais. Se alias não for informado, o SDK gera automaticamente um código alfanumérico de 10 caracteres. Em pix e boleto, expiresInDays é opcional (a API usa 0 quando omitido); recomenda-se informá-lo explicitamente.

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 (ex: https://link.conta.paybeehive.com.br/alias_alterado)

List payment links

A API não aceita filtros por query parameters; retorna todos os links da empresa.

payment_links = beehive.payment_links.list()

Get a payment link

payment_link = beehive.payment_links.get(247)

Update a payment link

Aceita atualizações parciais (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},
    },
})

Delete a payment link

beehive.payment_links.delete(247)

Error Handling

The SDK raises specific exception classes for different scenarios:

• BeehiveHubAPIError - General API errors (4xx, 5xx)
• BeehiveHubAuthenticationError - Authentication failures (401)
• BeehiveHubValidationError - Request validation errors (400)
• BeehiveHubNotFoundError - Resource not found (404)
• BeehiveHubRateLimitError - Rate limit exceeded (429)
• BeehiveHubNetworkError - Network/connection errors

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}")

Values in Cents

All monetary values in the API are expressed in cents.

# BRL 100.00 = 10000 cents
amount = 10000

# BRL 1.50 = 150 cents
amount = 150

# Convert reais to cents
reais = 100.0
cents = round(reais * 100)  # 10000

Security Best Practices

1. Never expose your SECRET_KEY - Use environment variables
2. Don't generate card_hash on backend - Use Beehive Hub's JavaScript library on frontend
3. Validate user data - Always validate and sanitize before sending to API
4. Use HTTPS - Always use secure connections
5. Implement webhooks - Receive status change notifications

# Requires: pip install python-dotenv
# .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"])

Type Safety

The SDK exports 40+ Pydantic models and ships with a py.typed marker, providing full support for type checkers like mypy and pyright.

from beehivehub import CreateTransactionData, Document, Item

data: CreateTransactionData = {
    "amount": 10000,
    "paymentMethod": "pix",
    "customer": {
        "name": "João Silva",
        "email": "joao@example.com",
        "document": {"type": "cpf", "number": "00000000191"},
        "phone": "11999999999",
    },
    "items": [
        {"title": "Produto Teste", "unitPrice": 10000, "quantity": 1, "tangible": True}
    ],
}

Development

Setup

git clone https://github.com/paybeehive/beehivehub-python-sdk.git
cd beehivehub-python-sdk
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Available commands

The project uses taskipy as task runner:

task test              # Run unit tests
task test-integration  # Run integration tests (requires .env with API key)
task lint              # Run linter (ruff)
task format            # Format code (ruff)
task typecheck         # Run type checker (mypy)
task coverage-html     # Generate HTML coverage report

Versioning

task bump-patch        # 1.0.0 → 1.0.1
task bump-minor        # 1.0.0 → 1.1.0
task bump-major        # 1.0.0 → 2.0.0

Support

For suggestions, bug reports, or questions:

• Email: contato@paybeehive.com.br
• Documentation: https://docs.beehivehub.io

License

This project is licensed under the MIT License - see the LICENSE file for details.