> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beehivehub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Java

<Card color="#f89820" icon="java" iconType="brands" href="https://github.com/paybeehive/beehivehub-java-sdk" title="Java">
  SDK oficial para integração com a API do Beehive Hub. Aceite pagamentos de forma simples e rápida.
</Card>

## Requisitos

* Java 11 ou superior
* Maven ou Gradle

## Instalação

**Maven** — adicione ao seu `pom.xml`:

```xml theme={null}
<dependency>
    <groupId>br.com.paybeehive</groupId>
    <artifactId>beehivehub-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

**Gradle:**

```gradle theme={null}
implementation 'br.com.paybeehive:beehivehub-java-sdk:1.0.0'
```

## Autenticação

Inicialize o SDK com a sua `SECRET_KEY`:

```java theme={null}
import br.com.paybeehive.sdk.BeehiveHubClient;

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));
```

## Ambiente Sandbox

Se quiser usar o ambiente de testes:

```java theme={null}
BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"), "sandbox");
```

## Primeiro uso

Exemplo de criação de uma transação Pix:

```java theme={null}
import br.com.paybeehive.sdk.BeehiveHubClient;
import br.com.paybeehive.sdk.models.Transaction;
import br.com.paybeehive.sdk.requests.CreateTransactionRequest;

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));

CreateTransactionRequest request = new CreateTransactionRequest();
request.setAmount(15990L);
request.setPaymentMethod("pix");
request.setPostbackUrl("https://seusite.com/webhook");

Transaction transaction = beehive.transactions.create(request);
System.out.println("Transação criada: " + transaction.getId());
```

## 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

```java theme={null}
CreateTransactionRequest request = new CreateTransactionRequest();
request.setAmount(8900L);
request.setPaymentMethod("pix");
request.setPostbackUrl("https://seusite.com/webhook");

Transaction transaction = beehive.transactions.create(request);
```

### Listar transações

```java theme={null}
ListTransactionsParams params = new ListTransactionsParams();
params.setLimit(50);
params.setOffset(0);
params.setStartDate("2026-01-01T00:00:00");

List<Transaction> transactions = beehive.transactions.list(params);
```

### Buscar transação por ID

```java theme={null}
Transaction transaction = beehive.transactions.get(123456L);
```

### Reembolsar transação

```java theme={null}
// Reembolso total
beehive.transactions.refund(123456L, null);

// Reembolso parcial
beehive.transactions.refund(123456L, 3000L);
```

### Atualizar status de entrega

```java theme={null}
UpdateDeliveryStatusRequest request = new UpdateDeliveryStatusRequest();
request.setStatus("in_transit");
request.setTrackingCode("BR123456789");

beehive.transactions.updateDelivery(123456L, request);
```

***

## Clientes

### Criar cliente

```java theme={null}
import br.com.paybeehive.sdk.models.Address;
import br.com.paybeehive.sdk.models.Document;

Document document = new Document();
document.setType("cpf");
document.setNumber("98765432100");

Address address = new Address();
address.setStreet("Rua Exemplo");
address.setStreetNumber("200");
address.setComplement("Sala 3");
address.setNeighborhood("Centro");
address.setZipCode("01001000");
address.setCity("São Paulo");
address.setState("SP");
address.setCountry("br");

CreateCustomerRequest request = new CreateCustomerRequest();
request.setName("Mariana Costa");
request.setEmail("mariana@email.com");
request.setPhone("11977777777");
request.setDocument(document);
request.setAddress(address);

Customer customer = beehive.customers.create(request);
```

### Listar clientes

> O parâmetro `email` é obrigatório nessa listagem. A API não utiliza paginação convencional para este recurso.

```java theme={null}
List<Customer> customers = beehive.customers.list("cliente@example.com");
```

### Buscar cliente por ID

```java theme={null}
Customer customer = beehive.customers.get(123456L);
```

***

## Transferências

### Criar transferência

```java theme={null}
CreateTransferRequest request = new CreateTransferRequest();
request.setAmount(50000L);
request.setRecipientId(916L);

Transfer transfer = beehive.transfers.create(request);
```

### Buscar transferência por ID

```java theme={null}
Transfer transfer = beehive.transfers.get(123456L);
```

***

## Saldo

### Consultar saldo

```java theme={null}
Balance balance = beehive.balance.get();

System.out.println("Available: BRL " + balance.getAmount() / 100.0);
System.out.println("Recipient ID: " + balance.getRecipientId());
```

***

## Recebedores

### Criar recebedor

```java theme={null}
CreateRecipientRequest request = new CreateRecipientRequest();
request.setLegalName("Recebedor Teste Ltda");

Recipient recipient = beehive.recipients.create(request);
```

### Listar recebedores

```java theme={null}
List<Recipient> recipients = beehive.recipients.list();
```

### Buscar recebedor por ID

```java theme={null}
Recipient recipient = beehive.recipients.get(916L);
```

### Atualizar recebedor

```java theme={null}
UpdateRecipientRequest request = new UpdateRecipientRequest();
request.setLegalName("Beehive Sandbox");

Recipient updated = beehive.recipients.update(916L, request);
```

***

## Contas bancárias

### Adicionar conta bancária a um recebedor

```java theme={null}
CreateBankAccountRequest request = new CreateBankAccountRequest();
request.setBankCode("341");
request.setAgencyNumber("9876");
request.setAccountNumber("54321");
request.setAccountDigit("0");
request.setType("conta_poupanca");
request.setLegalName("Empresa Teste Ltda");
request.setDocumentNumber("60572883000136");
request.setDocumentType("cnpj");

BankAccount bankAccount = beehive.bankAccounts.create(916L, request);
```

### Listar contas bancárias

```java theme={null}
List<BankAccount> accounts = beehive.bankAccounts.list(916L);
```

***

## Empresa

### Consultar dados da empresa

```java theme={null}
Company company = beehive.company.get();
```

### Atualizar dados da empresa

```java theme={null}
UpdateCompanyRequest request = new UpdateCompanyRequest();
request.setInvoiceDescriptor("Beehive Hub");

UpdateCompanyRequest.Details details = new UpdateCompanyRequest.Details();
details.setAverageRevenue(10000L);
details.setAverageTicket(100L);
details.setPhysicalProducts(true);
details.setProductsDescription("Produtos físicos");
details.setSiteUrl("https://www.meusite.com.br");
details.setPhone("11999999999");
details.setEmail("contato@meusite.com.br");
request.setDetails(details);

Company updated = beehive.company.update(request);
```

***

## Links de pagamento

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.

### Criar link de pagamento

```java theme={null}
CreatePaymentLinkRequest request = new CreatePaymentLinkRequest();
request.setTitle("Meu Link de Pagamento");
request.setAlias("alias_alterado");
request.setAmount(1000L);

PaymentLink paymentLink = beehive.paymentLinks.create(request);
// paymentLink.getUrl() já vem montada
```

### Listar links de pagamento

> A API não aceita filtros por query parameters nesse recurso. A listagem retorna todos os links da empresa.

```java theme={null}
List<PaymentLink> paymentLinks = beehive.paymentLinks.list();
```

### Buscar link de pagamento por ID

```java theme={null}
PaymentLink paymentLink = beehive.paymentLinks.get(247L);
```

### Atualizar link de pagamento

> A atualização aceita payload parcial, ou seja, você pode enviar apenas os campos que deseja alterar.

```java theme={null}
UpdatePaymentLinkRequest request = new UpdatePaymentLinkRequest();
request.setTitle("Link Atualizado");
request.setAmount(2000L);

PaymentLink updated = beehive.paymentLinks.update(247L, request);
```

### Excluir link de pagamento

```java theme={null}
beehive.paymentLinks.delete(247L);
```

***

## Tratamento de erros

O SDK expõe classes específicas para tratamento de erro:

* `BeehiveHubAPIError`
* `BeehiveHubAuthenticationError`
* `BeehiveHubValidationError`
* `BeehiveHubNotFoundError`
* `BeehiveHubRateLimitError`
* `BeehiveHubNetworkError`

Exemplo:

```java theme={null}
import br.com.paybeehive.sdk.BeehiveHubClient;
import br.com.paybeehive.sdk.exceptions.*;

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));

try {
    Transaction transaction = beehive.transactions.create(request);
    System.out.println("Transação criada: " + transaction.getId());
} catch (BeehiveHubAuthenticationError e) {
    System.err.println("Chave inválida: " + e.getMessage());
} catch (BeehiveHubValidationError e) {
    System.err.println("Erro de validação: " + e.getMessage());
} catch (BeehiveHubNotFoundError e) {
    System.err.println("Não encontrado: " + e.getMessage());
} catch (BeehiveHubRateLimitError e) {
    System.err.println("Rate limit excedido: " + e.getMessage());
} catch (BeehiveHubAPIError e) {
    System.err.println("Erro na API: " + e.getMessage());
} catch (BeehiveHubNetworkError e) {
    System.err.println("Erro de rede: " + e.getMessage());
}
```

***

## Valores em centavos

Todos os valores monetários enviados para a API devem ser informados em centavos.

```java theme={null}
// R$ 100,00
request.setAmount(10000L);

// R$ 1,50
request.setAmount(150L);

// Convertendo reais para centavos
double reais = 100.0;
long cents = Math.round(reais * 100); // 10000
```

***

## Boas práticas de segurança

* Nunca exponha sua `SECRET_KEY`
* Valide os dados antes de enviar para a API
* Use HTTPS
* Implemente webhooks para acompanhar mudanças de status

```java theme={null}
// Defina a variável de ambiente: BEEHIVE_SECRET_KEY=your_secret_key_here

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));
```