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

# QR Codes

> Gere e decodifique QR Codes Pix via BTG: BR Codes estáticos, cobranças imediatas COB e com vencimento COBV, payloads EMV e o decodificador universal de QR Code.

O Plugin Pix Indireto (BTG) gera e gerencia QR Codes Pix (BR Codes) para que seus clientes possam receber pagamentos. O plugin aceita quatro tipos de QR Code: BR Codes estáticos, cobranças imediatas (COB), cobranças com vencimento (COBV) e um decodificador para iniciação de pagamento.

Todos os QR Codes seguem a especificação EMV QCO e embutem a chave Pix do recebedor. Antes de você criar um QR Code, a chave do recebedor deve existir no DICT. A conta que faz a requisição deve ser dona da chave. Você identifica a conta com o header `X-Account-Id`. Veja o [guia do DICT](/pt/interfaces/pix-btg/indirect-pix-dict) para o cadastro de chaves.

# Como escolher o tipo de QR Code

***

| Tipo                      | Características                                                                                    | Melhor para                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Estático**              | Reutilizável (vários pagamentos) · valor opcional (fixo ou informado pelo pagador) · sem expiração | Telas de POS, material impresso, doações, e-commerce com valores variáveis |
| **Imediata (COB)**        | Pagamento único · valor obrigatório · expiração em segundos                                        | Checkout, faturamento, compras avulsas                                     |
| **Com vencimento (COBV)** | Pagamento único · valor + encargos · vencimento + carência                                         | Contas, parcelas, assinaturas, faturamento B2B (como um boleto)            |
| **Decodificação**         | Lê qualquer QR Code escaneado                                                                      | Iniciar um pagamento a partir de um código escaneado                       |

# QR Codes estáticos

***

Os BR Codes estáticos (`/v1/brcode/static`) são reutilizáveis. Pagadores diferentes podem pagar o mesmo código muitas vezes. Cada código se liga a uma chave Pix e, opcionalmente, a dados do estabelecimento.

**Valor fixo ou variável:**

* **Com valor**: o pagador escaneia e confirma um valor predefinido. Útil para itens de preço fixo.
* **Sem valor**: o pagador escaneia e digita o valor manualmente. Útil para doações ou checkout aberto.

Você pode adicionar dados do estabelecimento ao código: `merchant.name`, `merchant.city`, `merchant.categoryCode` (MCC) e `merchant.postalCode`. Você também pode adicionar um `txId` opcional (alfanumérico, até 25 caracteres) para conciliação. Se você omitir os dados do estabelecimento, o plugin os preenche a partir dos dados do titular no CRM.

```json theme={null}
POST /v1/brcode/static
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "receiverKey": "+5511999999999",
  "amount": "100.00",
  "description": "Payment for order #12345",
  "txId": "TX123ABC",
  "merchant": { "name": "Loja ABC", "city": "São Paulo", "categoryCode": "5411" }
}
→ 201 Created  { "id": "...", "emv": "00020126580014br.gov.bcb.pix..." }
```

Passe `include_base64=true` para receber também um PNG do QR Code codificado em Base64. O plugin valida que a conta é dona da chave do recebedor antes de criar o código.

**Referência:** [Criar um QR code estático](/pt/reference/interfaces/pix-btg/create-a-static-qr-code) · [Listar](/pt/reference/interfaces/pix-btg/list-static-qr-codes) · [Consultar](/pt/reference/interfaces/pix-btg/retrieve-a-static-qr-code)

# Cobranças imediatas (COB)

***

As cobranças imediatas (`/v1/collections/immediate`), ou COB, são QR Codes dinâmicos de uso único. Cada cobrança define um valor específico e uma janela de validade curta. Um `txId` obrigatório identifica cada cobrança. Um pagador pode liquidar uma cobrança apenas uma vez.

**Campos obrigatórios:** `amount`, `expirationSeconds`, `receiverKey` e `txId`. Os campos opcionais `debtorName` e `debtorDocument` identificam o pagador pretendido.

**Ciclo de vida:**

| Status      | Significado                        |
| ----------- | ---------------------------------- |
| `ACTIVE`    | Criada e disponível para pagamento |
| `COMPLETED` | Pagamento recebido com sucesso     |
| `EXPIRED`   | Janela de validade encerrada       |
| `DELETED`   | Cancelada pelo estabelecimento     |

Quando você cria uma cobrança, o plugin agenda um job de expiração. Depois que `expirationSeconds` se esgota, a cobrança passa para `EXPIRED` e nenhum pagador consegue liquidá-la. Você pode atualizar (`PUT`) ou apagar (`DELETE`) uma cobrança apenas enquanto ela está `ACTIVE`.

**Confirmação de pagamento:** quando um Pix recebido liquida a cobrança, o plugin a move para `COMPLETED`. Em seguida, o plugin emite um webhook para avisar seu sistema em tempo real. Veja o [guia de Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks) e o [guia de Cobranças](/pt/interfaces/pix-btg/indirect-pix-collections) para o fluxo completo de pagamento.

**Referência:** [Criar uma cobrança imediata](/pt/reference/interfaces/pix-btg/create-an-immediate-charge) · [Listar](/pt/reference/interfaces/pix-btg/list-immediate-charges) · [Consultar](/pt/reference/interfaces/pix-btg/retrieve-immediate-charge-details) · [Atualizar](/pt/reference/interfaces/pix-btg/update-an-immediate-charge) · [Apagar](/pt/reference/interfaces/pix-btg/delete-an-immediate-charge)

# Cobranças com vencimento (COBV)

***

As cobranças com vencimento (`/v1/collections/duedate`), ou COBV, são QR Codes dinâmicos para faturamento com data de vencimento, como um boleto. Elas aceitam regras de valor complexas. Elas exigem os dados completos do devedor e do recebedor.

**Campos principais:** `dueDate`, `validAfterDue`, um `debtor` obrigatório e um objeto `amount`. O campo obrigatório `validAfterDue` define por quantos dias a cobrança continua pagável depois do vencimento. O `debtor` precisa de um nome e de um CPF ou CNPJ. Ele também aceita os campos opcionais email, address, city, state e zipCode. O objeto `amount` guarda o valor `original` e os componentes de encargo opcionais:

| Componente  | Modalidade                                                   | Aplicação                           |
| ----------- | ------------------------------------------------------------ | ----------------------------------- |
| `fine`      | `FIXED_VALUE` ou `PERCENT`                                   | Multa por atraso no pagamento       |
| `interest`  | por exemplo, `PERCENTAGE_PER_MONTH_CALENDAR_DAYS`            | Incide depois do vencimento         |
| `discount`  | uma modalidade com um valor, ou um array `discountDateFixed` | Benefício pelo pagamento antecipado |
| `abatement` | `FIXED_VALUE` ou `PERCENT`                                   | Redução sobre o valor               |

O momento do pagamento determina o valor final. Antes do vencimento, o pagador recebe o desconto que houver. No dia do vencimento, vale o valor `original`. Depois do vencimento, o plugin soma a multa e os juros, depois subtrai o abatimento que houver. Um desconto com data (`discountDateFixed`) precisa de uma `date` anterior ao `dueDate`.

O plugin exige um documento válido do devedor (CPF ou CNPJ). Ele mantém a cobrança pagável até o vencimento mais `validAfterDue` dias.

**Referência:** [Criar uma cobrança com vencimento](/pt/reference/interfaces/pix-btg/create-a-dynamic-charge-with-due-date) · [Listar](/pt/reference/interfaces/pix-btg/list-dynamic-charges-with-due-date) · [Consultar](/pt/reference/interfaces/pix-btg/retrieve-dynamic-charge-with-due-date-details) · [Atualizar](/pt/reference/interfaces/pix-btg/update-a-dynamic-charge-with-due-date)

# Decodificação de QR Codes

***

O decodificador (`POST /v1/qrcodes/decode`) interpreta qualquer QR Code Pix escaneado. Ele retorna os dados de pagamento embutidos. Use-o em fluxos de iniciação de pagamento. Um cliente escaneia um QR Code, e você lê o recebedor, o valor e os detalhes da cobrança antes de confirmar o pagamento.

O plugin detecta o tipo do QR Code automaticamente e retorna uma resposta tipada:

* **STATIC**: chave do recebedor, valor e descrição opcionais, dados do estabelecimento, `txId`.
* **IMMEDIATE (COB)**: todos os campos do estático mais valor obrigatório, expiração, status e número de revisão.
* **DUE\_DATE (COBV)**: todos os campos do imediato mais vencimento, `validAfterDue`, devedor, recebedor e a estrutura completa de multa, juros e desconto.

Para códigos dinâmicos, o plugin resolve o payload no BTG antes de responder. A resposta reflete o estado atual da cobrança.

```json theme={null}
POST /v1/qrcodes/decode
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "emv": "00020126580014br.gov.bcb.pix..." }
→ 200 OK  { "type": "IMMEDIATE", "amount": "100.00", "receiverKey": "...", "status": "ACTIVE" }
```

**Referência:** [Decodificar um QR code Pix](/pt/reference/interfaces/pix-btg/decode-a-pix-qr-code)

# Próximos passos

***

* [Cobranças](/pt/interfaces/pix-btg/indirect-pix-collections): Ciclo de vida da cobrança, vínculo com o pagamento e eventos de webhook
* [DICT](/pt/interfaces/pix-btg/indirect-pix-dict): Cadastro das chaves Pix em que seus QR Codes recebem
* [Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks): Notificações de pagamento e de status