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

# POST /pix-qr

> Gere strings PIX Copia e Cola e QR codes para pagamentos instantâneos brasileiros.

## Endpoint

```
POST https://api.bunny.build/api/v1/pix-qr
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Gere strings PIX Copia e Cola válidas e QR codes escaneáveis para o sistema de pagamento instantâneo brasileiro. Forneça uma chave PIX, nome do beneficiário, cidade e valor opcional para receber um payload totalmente compatível e uma imagem QR code em base64 pronta para incorporar no seu checkout, fatura ou recibo.

## Casos de uso

* Incorporar QR code PIX em páginas de checkout para pagamento instantâneo
* Gerar links de doação para organizações sem fins lucrativos e campanhas
* Automatizar a geração de faturas com IDs de transação únicos
* Habilitar fluxos de pagamento entre pessoas em aplicativos fintech

## Corpo da requisição

| Campo         | Tipo   | Obrigatório | Descrição                                                           |
| ------------- | ------ | ----------- | ------------------------------------------------------------------- |
| `key`         | string | Sim         | Chave PIX: número de telefone, CPF, e-mail ou EVP (chave aleatória) |
| `name`        | string | Sim         | Nome do beneficiário (máx. 25 caracteres)                           |
| `city`        | string | Sim         | Cidade do beneficiário (máx. 15 caracteres)                         |
| `amount`      | number | Não         | Valor em BRL. Omita para transações de valor aberto                 |
| `description` | string | Não         | Descrição da transação (máx. 72 caracteres)                         |
| `txid`        | string | Não         | ID da transação para conciliação                                    |

### Exemplo

```json theme={null}
{
  "key": "11999887766",
  "name": "Bunny Build",
  "city": "Sao Paulo",
  "amount": 10.00
}
```

## Resposta

### 200 OK

| Campo       | Tipo   | Descrição                             |
| ----------- | ------ | ------------------------------------- |
| `payload`   | string | String PIX Copia e Cola (formato EMV) |
| `qr_base64` | string | Imagem QR code PNG em base64          |
| `mime_type` | string | Tipo MIME da imagem QR code           |
| `key`       | string | Chave PIX utilizada                   |
| `name`      | string | Nome do beneficiário                  |
| `city`      | string | Cidade do beneficiário                |
| `amount`    | number | Valor em BRL, se fornecido            |

**Exemplo**

```json theme={null}
{
  "payload": "00020126330014BR.GOV.BCB.PIX0111119998877665204000053039865406100.005802BR5911Bunny Build6009Sao Paulo62070503***6304ABCD",
  "qr_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mime_type": "image/png",
  "key": "11999887766",
  "name": "Bunny Build",
  "city": "Sao Paulo",
  "amount": 10.00
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Fields 'key', 'name', and 'city' are required."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/pix-qr \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "11999887766", "name": "Bunny Build", "city": "Sao Paulo", "amount": 10.00}'
```