# Beehive Pay – Contexto para IAs

> A Beehive Pay (razão social: Beehive Pagamentos Inteligentes LTDA) é uma fintech brasileira de pagamentos via API. Permite cobrar clientes por checkout, transações PIX (incluindo QR Code), cartão com tokenização e 3DS, links de pagamento, além de oferecer webhooks e operação com MCP para automação por agentes. A API segue REST + JSON e opera em BRL. Base URL: `https://api.conta.paybeehive.com.br/v1`.
> Documento gerado automaticamente para uso como contexto por agentes de IA.
> Versão: 1.0.0 · Gerado em: 2026-05-07T16:11:19.354Z
> Fonte oficial: https://docs.beehivehub.io


## Notas Importantes

- **Autenticação:** todas as requisições à API exigem o header `Authorization: Bearer <sua-api-key>`, onde `<sua-api-key>` corresponde a `base64(SECRET_KEY:x)` (autenticação Basic encapsulada no esquema Bearer). **Boa prática:** a `SECRET_KEY` nunca deve ser exposta no front-end — sempre chame a API a partir do backend. Em integrações que exponham frontend ao browser (checkout/CORS), configure também os headers de CORS no servidor que faz proxy.

- **Transações PIX:** a resposta retorna o campo `qrCode` (texto/copia-e-cola). A imagem do QR Code **não é retornada pela API** — é responsabilidade do cliente/aplicação gerar a imagem (ex.: PNG/SVG) a partir do `qrCode` para exibi-la ao pagador. Em aplicações frontend/checkout é **obrigatório renderizar o QR Code visualmente** (para escaneamento) e oferecer o `qrCode` em texto como fallback de copia-e-cola. Não basta devolver apenas o texto — exibir o QR Code é parte obrigatória da experiência de pagamento.

- **Metadata obrigatório:** toda transação exige o objeto `metadata` com `provider`, `user_email`, `order_id`, `checkout_url` e `shop_url`. O campo `shop_url` deve apontar para o **domínio que identifica o produto/canal** onde a transação está sendo realizada (ex.: site institucional, web app, marketplace, app mobile). Omitir `metadata` invalida a requisição.

- **Valores monetários:** sempre expressos em **centavos** e em BRL. Exemplo: `10000` = R$ 100,00. Aplica-se a `amount`, `unitPrice`, `refundedAmount`, `fee.fixedAmount`, etc.

- **Customer obrigatório:** toda transação exige `customer.name`, `customer.email` e `customer.document` (objeto com `number` e, opcionalmente, `type` — ex.: `cpf`). Omitir qualquer um invalida a requisição.

- **Tokenização de cartão no front-end (PCI-DSS):** dados de cartão (número, CVV, validade) devem ser **tokenizados exclusivamente no front-end** via script Beehive (`BeehivePay.encrypt`). Apenas o token gerado deve trafegar para o backend. Nunca envie dados brutos do cartão para o seu servidor.

- **3DS quando emissor exigir:** em fluxos de cartão de crédito, quando o 3DS estiver disponível (`BeehivePay.is3DSAvailable()`), é obrigatório executar `BeehivePay.authenticate3DS` e exibir a tela de autenticação ao usuário antes de criar a transação. Omitir essa etapa pode resultar em recusa pela bandeira/emissor.

- **postbackUrl para webhooks:** sempre informar `postbackUrl` na criação da transação/checkout para receber notificações de mudança de status em tempo real (eventos `transaction`, `checkout`, `transfer`). O endpoint deve aceitar `POST` com payload JSON.

- **Campos condicionais por método de pagamento:**
  - `credit_card`: enviar `card` (token gerado pela tokenização) e `installments` (número de parcelas).
  - `pix`: pode incluir `pix.expiresInSeconds` (opcional).
  - `boleto`: pode incluir `boleto.expiresInDays` (opcional).


## Visão geral

API Beehive Pay

API pública da Beehive Pay para criar e gerenciar transações, clientes, reembolsos,
transferências, recebedores, contas bancárias, saldo, empresa, checkouts.

Autenticação:
- Basic Authorization (ex.: "Basic base64(SECRET_KEY:x)")
- ou x-api-key (se habilitado no seu gateway)

**Fluxo para conectar e usar:** configurar chave em Configurações → Credenciais de API → chamar a API com autenticação Basic → criar transação (POST /transactions).

## Bem-vindo à nossa documentação de API!

### Como navegar pela documentação
Para facilitar sua jornada, organizamos a documentação em etapas simples e objetivas. Siga cada uma delas para aproveitar ao máximo nossa API!
*   **Introdução**: Visão geral e primeiros passos.
*   **Autenticação**: Como garantir acesso seguro à API.
*   **Tokenização de Cartão de Crédito**: Protegendo dados sensíveis.
*   **Entrando em Produção**: Dicas para migrar do ambiente de testes para o real.
*   **Webhook**: Automatizando notificações e integrações.

### Sobre a API
Nossa API segue os padrões **REST**. Todas as respostas são enviadas no formato **JSON**.

Para autenticar, você deve passar sua **chave secreta** seguindo o padrão Basic Access Authentication (https://en.wikipedia.org/wiki/Basic_access_authentication).

### Onde encontrar suas chaves
Acesse o menu: Configurações → Credenciais de API (https://app.conta.paybeehive.com.br/settings/credentials)
ou clique no botão localizado no canto superior direito "Credenciais".

Ali você verá:
*   **Chave secreta** (para autenticação na API)
*   **Chave pública** (uso client-side, não serve para autenticar na API)


## Autenticação

A Beehive utiliza **autenticação Basic** (SECRET_KEY codificada em base64 no formato `SECRET_KEY:x`), porém o header HTTP é configurado com o esquema **Bearer**.

**Formato do header (obrigatório em todas as chamadas):**

```
Authorization: Bearer <base64(SECRET_KEY:x)>
```

- Método de autenticação: **Basic** (credencial = `SECRET_KEY:x` em base64)
- Esquema do header: **Bearer** (o token base64 é enviado após `Bearer `)
- Obtenha a chave em **Configurações → Credenciais de API** (https://app.conta.paybeehive.com.br/settings/credentials)
- A `SECRET_KEY` **nunca** deve ser exposta no front-end

**Orientações para agentes/IA:** Em integrações que exponham frontend ou APIs ao browser (checkout, CORS), é **obrigatório configurar os CORS headers** no servidor que faz proxy ou que expõe a API (ex.: `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`) para que as requisições do cliente sejam aceites pelo browser.


## Como adicionar o MCP Beehive ao seu cliente

O **MCP Beehive** é um servidor MCP (Model Context Protocol) que expõe tools para a API Beehive: create_transaction, get_transaction, list_transactions, get_balance. Permite que clientes (ex.: Cursor) criem e consultem transações via tools, sem chamar a API REST diretamente.

**Passos para adicionar ao cliente (ex.: Cursor):**
1. Abrir definições MCP do cliente (ex.: Cursor → Settings → MCP, ou ficheiro de config MCP no projeto).
2. Adicionar servidor tipo **stdio**: comando que inicia o mcp-server (ex.: a partir do diretório do repo, `npx` com args `tsx`, `mcp-server/src/index.ts`, e working directory `mcp-server`; ou caminho absoluto ao script). Exemplo de config (JSON): command = "npx", args = ["tsx", "src/index.ts"], cwd = "mcp-server".
3. Definir variável de ambiente **SECRET_KEY** no bloco env da config MCP (valor = chave secreta da API Beehive). Opcional: BEEHIVE_API_BASE_URL se usar outra base.
4. Obter a chave em **Configurações → Credenciais de API** (Beehive): https://app.conta.paybeehive.com.br/settings/credentials — nunca no front.
5. Executar o servidor: no terminal, `cd mcp-server && npm run dev` (ou `npx tsx src/index.ts`). O cliente MCP usa **stdio** para comunicar com o processo; não é necessário expor porta HTTP.

Após guardar a config, o cliente pode invocar as tools (get_balance, create_transaction, etc.) sem consultar documentação externa dispersa.

**Onde descobrir o MCP Beehive:** a listagem com nome, descrição e instruções de configuração está na documentação do repositório: **docs/mcp-beehive.md** (no repo). No site/documentação do projeto, consulte também a secção "Integração com MCP" no README da raiz ou o **mcp-server/README.md** (Como adicionar ao Cursor).


## Transação (criar, obter, listar)

Endpoints (OpenAPI):

- /transactions
- /transactions/{transactionId}
- /transactions/{transactionId}/refund
- /customers
- /customers/{customerId}
- /transfers
- /transfers/{transferId}
- /balance
- /recipients
- /recipients/{recipientId}
- /recipients/{recipientId}/bank-accounts
- /recipients/{recipientId}/bank-accounts/{bankAccountId}
- /company
- /checkouts
- /checkouts/{checkoutId}
- /webhooks/events


### Campos obrigatórios para criar transação (POST /transactions)

Conforme a API Beehive (openapi.yaml), o body **TransactionCreateRequest** exige:

- **amount** (integer): valor em centavos (ex.: 5000 = R$ 50,00)
- **paymentMethod** (string): `credit_card` | `boleto` | `pix`
- **customer** (objeto): dados do cliente — obrigatórios: **name**, **email**, **document** (objeto com `number` e opcionalmente `type`, ex.: cpf)
- **items** (array): pelo menos um item; cada item exige **title**, **unitPrice** (centavos), **quantity**, **tangible** (boolean)
- **metadata** (objeto): obrigatório na API — **provider**, **user_email**, **order_id**, **checkout_url**, **shop_url**
- **postbackUrl** (string, opcional): URL para receber webhooks de notificação de status da transação

Condicionais por forma de pagamento:
- **credit_card:** enviar **card** (token/hash da tokenização) e **installments** (número de parcelas)
- **pix:** pode incluir objeto **pix** com `expiresInSeconds` (opcional)
- **boleto:** pode incluir objeto **boleto** com `expiresInDays` (opcional)

**Orientações para agentes/IA:** Ao gerar código ou instruções para criar uma transação, incluir sempre estes campos obrigatórios (customer.name, customer.email, customer.document, items, metadata). Omitir metadata ou customer invalida a requisição (API retorna erro).


## PIX

A resposta da API para transação PIX inclui código/QR para o pagador. A geração de base64 (ou imagem) para exibir o QR code é responsabilidade do cliente/aplicação. **Orientações para agentes/IA:** Em aplicações frontend ou checkout, é necessário **gerar e exibir a imagem do QR code PIX** (a partir do payload da transação) para que o utilizador final possa pagar; não basta devolver apenas o texto/código — a experiência de uso exige a imagem do QR code visível na interface.


## Cartão (tokenização e 3DS)

Tokenização no front-end: usar script Beehive (ex.: https://api.conta.paybeehive.com.br/v1/js, BeehivePay.encrypt). Fluxo 3DS: authenticate3DS no front → encrypt (token do cartão) → enviar token para o backend criar a transação.

### O fluxo correto é:

1. **Tokenizar** os dados do cartão no front-end
2. Receber um **token seguro**
3. Enviar esse token na requisição de criação da transação no back-end

Esse processo garante conformidade com **PCI-DSS**, reduz sua superfície de risco e impede que dados sensíveis passem pelo seu servidor.

### Incluindo a biblioteca de tokenização

A tokenização é feita **exclusivamente no front-end**, usando nossa biblioteca JavaScript.

Basta adicionar o script abaixo **no <head> da sua página**:

```javascript
<script src="https://api.conta.paybeehive.com.br/v1/js"></script>
```

Esse script carrega a engine de criptografia responsável por transformar os dados reais do cartão em um token seguro.

### Configurando a biblioteca

Antes de gerar qualquer token, você precisa definir:

- A **chave pública** da sua company (obtida em Configurações → Credenciais de API)
- Se o ambiente está em **modo de teste** ou produção

```javascript
BeehivePay.setPublicKey("SUA_CHAVE_PUBLICA_AQUI");
BeehivePay.setTestMode(true); // Defina false em produção
```

A chave pública **não oferece risco** — ela foi criada exatamente para ser usada no front-end.

### Gerando o token do cartão (encrypt)

Após o cliente digitar os dados do cartão e clicar em finalizar compra, você chama:

```javascript
var token = await BeehivePay.encrypt({
  number: "4111111111111111",
  holderName: "Bruce Wayne",
  expMonth: 1,
  expYear: 2025,
  cvv: "123"
});
```

O que acontece aqui:

- Os dados são criptografados diretamente no navegador
- Nenhuma informação sensível trafega pelo seu servidor
- Você recebe algo assim: `bhp_tok_6af98c4e1c6e4f0ab6d93e8e7d093fab`

Esse token representa o cartão e **pode ser enviado com segurança para o back-end**.


## Autenticação 3DS

Ao processar transações com cartão de crédito, a autenticação 3DS adiciona uma camada extra de segurança, reduzindo riscos de fraude e aumentando a aprovação das transações.

O fluxo correto é:

1. Importar o script de autenticação 3DS no front-end
2. Configurar a chave pública da empresa
3. Verificar se o 3DS está disponível
4. Realizar a autenticação 3DS
5. Tokenizar os dados do cartão
6. Enviar o token para o back-end criar a transação

Esse processo garante conformidade com padrões de segurança e protege dados sensíveis.

### Setup da biblioteca

Adicione o script da Beehive no `<head>` da sua página:

```html
<script src="https://api.conta.paybeehive.com.br/v1/js"></script>
```

### Configuração inicial

```javascript
BeehivePay.setPublicKey("pk_live_sua_chave_publica");
```

### Validação do 3DS

Antes de autenticar, verifique se o 3DS está habilitado:

```javascript
const is3DSAvailable = await BeehivePay.is3DSAvailable();
console.log("3DS disponível:", is3DSAvailable); // true ou false
```

### Autenticação 3DS

Se o 3DS estiver disponível, execute a autenticação:

```javascript
const card = {
  number: "4111111111111111",
  holderName: "Bruce Wayne",
  expMonth: 5,
  expYear: 2028,
  cvv: "123",
};

if (is3DSAvailable) {
  await BeehivePay.authenticate3DS({
    amount: 4990,       // valor em centavos
    currency: "brl",    // sempre "brl"
    installments: 2,    // número de parcelas
    card,
  });
}
```

### Tokenização

Após a autenticação, gere o token do cartão:

```javascript
const token = await BeehivePay.encrypt({
  number: "4111111111111111",
  holderName: "Bruce Wayne",
  expMonth: 5,
  expYear: 2028,
  cvv: "123",
});
```

### Envio da transação

No seu servidor, envie o token gerado para criar a transação via API, garantindo que a autenticação 3DS foi realizada com sucesso.

**Orientações para agentes/IA (cartão e 3DS):** Em fluxos com autenticação 3DS, a aplicação frontend/checkout deve **exibir a tela de autenticação 3DS** ao utilizador (iframe ou redirecionamento conforme documentação Beehive); não omitir esta etapa — é obrigatória para conformidade e aprovação da transação quando o emissor exigir 3DS.


## Webhooks

O sistema do seller recebe os webhooks (postbackUrl informado na transação/checkout); o MCP não recebe webhooks. Tipos de evento: transaction, checkout, transfer. Estrutura do payload: id, type, objectId, url, data (conforme doc-api).

Sempre que uma transação, checkout ou transferência muda de status, a Beehive envia automaticamente uma **notificação HTTP (POST)** para a URL que você informar no campo postbackUrl.

Essa URL deve ser um endpoint do seu sistema capaz de:
*   receber JSON via POST
*   validar e armazenar o evento
*   processar atualizações conforme sua lógica de negócio

Os postbacks permitem que seu sistema seja atualizado **em tempo real**, sem precisar ficar consultando a API.

### Estrutura do Payload

Todos os postbacks seguem um formato padrão:

```json
{
  "id": "<id do evento>",
  "type": "<transaction | checkout | transfer>",
  "objectId": "<id do objeto relacionado>",
  "url": "<sua URL de postback>",
  "data": {
    /* objeto completo com os detalhes do evento */
  }
}
```

### 1. Postback de Transação (type: "transaction")

Esse evento é enviado sempre que uma transação muda de status — por exemplo: created, processing, authorized, paid, refused, refunded.

**Exemplo completo:**

```json
{
    "id": 686401,
    "type": "transaction",
    "objectId": "282",
    "url": "https://test.com",
    "data": {
        "id": 282,
        "amount": 10000,
        "refundedAmount": 0,
        "companyId": 2,
        "installments": 12,
        "paymentMethod": "credit_card",
        "status": "paid",
        "postbackUrl": null,
        "metadata": null,
        "traceable": false,
        "secureId": "a4594817-be48-4a23-81aa-4bb01f95fe78",
        "secureUrl": "https://link.compra.com.br/pagar/a4594817-be48-4a23-81aa-4bb01f95fe78",
        "createdAt": "2022-07-18T09:54:22.000Z",
        "updatedAt": "2022-07-18T09:54:22.000Z",
        "paidAt": "2022-07-18T09:54:22.000Z",
        "ip": null,
        "externalRef": null,
        "customer": {
            "id": 1,
            "name": "Gabryel",
            "email": "gabryel@hotmail.com",
            "document": { "number": "12345678910", "type": "cpf" }
        },
        "card": {
            "brand": "visa",
            "holderName": "GABRYEL FERREIRA",
            "lastDigits": "1111",
            "expirationMonth": 3,
            "expirationYear": 2028
        },
        "items": [
            { "title": "b456", "unitPrice": 100, "quantity": 1, "tangible": false }
        ],
        "fee": {
            "fixedAmount": 200,
            "spreadPercentage": 4,
            "estimatedFee": 600,
            "netAmount": 9400
        }
    }
}
```

### 2. Postback de Checkout (type: "checkout")

Esse evento é disparado quando um checkout criado via Link de Pagamento é atualizado — por exemplo: ativação, atualização dos itens, ligação com a transação finalizada.

### 3. Postback de Transferência (type: "transfer")

Enviado quando uma transferência (Pix, TED, repasse interno) muda de status: bank_processing, processed, failed, transferred.

**Exemplo:**

```json
{
    "id": 388,
    "type": "transfer",
    "objectId": "237",
    "url": "https://test.com",
    "data": {
        "id": 237,
        "amount": 500,
        "status": "bank_processing",
        "pixKey": "12345678900",
        "fee": 0,
        "description": "Transferência Teste",
        "postbackUrl": "https://test.com",
        "processedAt": "2022-10-18T16:43:44.000Z"
    }
}
```


## Exemplos

### Exemplo: POST /transactions (curl)

```bash
curl -X POST https://api.conta.paybeehive.com.br/v1/transactions \
  -H "Authorization: Basic $(echo -n 'SECRET_KEY:x' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"paymentMethod":"pix","customer":{"name":"João","email":"joao@example.com","document":{"type":"cpf","number":"00000000191"}},"items":[{"title":"Produto","unitPrice":5000,"quantity":1,"tangible":true}],"metadata":{"provider":"my-shop","user_email":"joao@example.com","order_id":"ord-123","checkout_url":"https://myshop.com/checkout","shop_url":"https://myshop.com"},"postbackUrl":"https://myshop.com/webhook"}'
```

### Exemplo: body mínimo para criar transação (JSON)

Campos obrigatórios: amount (centavos), paymentMethod, customer (name, email, document), items (title, unitPrice, quantity, tangible), metadata (provider, user_email, order_id, checkout_url, shop_url), postbackUrl (recomendado para webhooks).

```json
{
  "amount": 5000,
  "paymentMethod": "pix",
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": { "type": "cpf", "number": "00000000191" }
  },
  "items": [
    { "title": "Produto", "unitPrice": 5000, "quantity": 1, "tangible": true }
  ],
  "metadata": {
    "provider": "my-shop",
    "user_email": "joao@example.com",
    "order_id": "ord-123",
    "checkout_url": "https://myshop.com/checkout",
    "shop_url": "https://myshop.com"
  },
  "postbackUrl": "https://myshop.com/webhook"
}
```


## Sobre a Beehive

- **Site:** https://paybeehive.com.br
- **Instagram:** https://instagram.com/paybeehive.com.br
- **Documentação oficial da API:** https://docs.beehivehub.io