# PIX QR Code

## Ciclo de Vida

### Fluxo de Criação e Pagamento

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API
    participant BC as Banco Central

    P->>B: POST /v1/account/{id}/pix/qrcode/dynamic
    B-->>P: 201 Created (status: CREATED)
    Note over B: QR Code gerado via provedor
    BC->>B: Pagamento recebido
    B-->>P: status: PAID
```

### Status

| Status       | Descrição                            |
| ------------ | ------------------------------------ |
| `CREATED`    | QR Code criado, aguardando pagamento |
| `PROCESSING` | Pagamento em processamento           |
| `PAID`       | QR Code pago com sucesso             |
| `FAILED`     | Falha no processamento do pagamento  |
| `EXPIRED`    | QR Code expirado sem pagamento       |

***

## POST /v1/account/{id}/pix/qrcode/dynamic

Cria um QR Code PIX dinâmico associado à conta informada. A chave PIX ativa da conta é utilizada automaticamente.

**Path Parameters:**

| Parâmetro | Tipo | Descrição                      |
| --------- | ---- | ------------------------------ |
| `id`      | UUID | ID da conta bancária (UUID v4) |

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v1/account/53bcb30e-c2df-4316-bbff-161ee01e34be/pix/qrcode/dynamic' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100.00,
    "description": "Pagamento de serviço",
    "expiration": 86400,
    "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
    "payer": {
      "name": "John Doe",
      "document": "12345678901"
    }
  }'
```

### Campos — Request

| Campo         | Tipo       | Obrigatório | Validação                                                                |
| ------------- | ---------- | ----------- | ------------------------------------------------------------------------ |
| `amount`      | BigDecimal | Sim         | Deve ser maior que zero. Ex: `100.00`                                    |
| `description` | String     | Não         | Descrição do pagamento. Ex: `Pagamento de serviço`                       |
| `expiration`  | Integer    | Não         | Tempo de expiração em segundos. Default: 86400 (24 horas). Ex: `3600`    |
| `externalId`  | String     | Não         | ID de referência do parceiro. Ex: `f1619a39-429f-4cc5-97fe-2da75b2e7f44` |
| `payer`       | Object     | Não         | Dados do pagador (ver tabela abaixo)                                     |

### Campos — Payer

| Campo      | Tipo   | Obrigatório | Validação                                                |
| ---------- | ------ | ----------- | -------------------------------------------------------- |
| `name`     | String | Não         | Nome completo do pagador. Ex: `John Doe`                 |
| `document` | String | Não         | CPF (11 dígitos) ou CNPJ (14 dígitos). Ex: `12345678901` |

**Response — 201 Created:**

```json
{
  "id": "53bcb30e-c2df-4316-bbff-161ee01e34be",
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
  "status": "CREATED",
  "description": "Pagamento de serviço",
  "pixKey": "486c486b-ddcd-495a-837a-be52f5989f3e",
  "amount": 100.00,
  "expiration": 86400,
  "expiresAt": "2026-03-13T19:16:15.46418",
  "qrCode": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/pc/p/v2/56b07da2bef94006adede26591fcf8b65204000053039865802BR5925NEW COMPANY BANKING 008706009SAO PAULO61080807215562070503***630446CD",
  "payer": {
    "name": "John Doe",
    "document": "12345678901"
  }
}
```

### Campos — Response

| Campo            | Tipo       | Descrição                                                          |
| ---------------- | ---------- | ------------------------------------------------------------------ |
| `id`             | UUID       | ID do QR Code gerado                                               |
| `accountId`      | UUID       | ID da conta bancária associada                                     |
| `externalId`     | String     | ID de referência do parceiro (se informado)                        |
| `status`         | String     | Status do QR Code. Ver tabela de status                            |
| `description`    | String     | Descrição do pagamento                                             |
| `pixKey`         | String     | Chave PIX utilizada para geração do QR Code                        |
| `amount`         | BigDecimal | Valor em reais. Ex: `100.00`                                       |
| `expiration`     | Integer    | Tempo de expiração em segundos                                     |
| `expiresAt`      | String     | Data/hora de expiração (ISO 8601). Ex: `2026-03-13T19:16:15.46418` |
| `qrCode`         | String     | Payload do QR Code PIX (EMV)                                       |
| `payer`          | Object     | Dados do pagador (se informado)                                    |
| `payer.name`     | String     | Nome do pagador                                                    |
| `payer.document` | String     | CPF ou CNPJ do pagador                                             |

**Response — 400 Bad Request (validação):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request amount - Amount must be greater than zero"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-03-12T19:16:15Z"
  }
}
```

**Response — 404 Not Found:**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Account 53bcb30e-c2df-4316-bbff-161ee01e34be not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-03-12T19:16:15Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                       |
| ------------------ | ----------------------------------------------- |
| `201 Created`      | QR Code criado com sucesso                      |
| `400 Bad Request`  | Dados inválidos ou campos obrigatórios ausentes |
| `401 Unauthorized` | Token inválido ou expirado                      |
| `403 Forbidden`    | Sem acesso à conta                              |
| `404 Not Found`    | Conta não encontrada                            |

***

## GET /v1/account/{id}/pix/qrcode/{qrcodeId}

Consulta os detalhes de um QR Code PIX por ID. O status de expiração é verificado e atualizado automaticamente.

> O `qrcodeId` pode ser tanto o ID interno (UUID) quanto o `externalId` do QR Code.

**Path Parameters:**

| Parâmetro  | Tipo | Descrição                      |
| ---------- | ---- | ------------------------------ |
| `id`       | UUID | ID da conta bancária (UUID v4) |
| `qrcodeId` | UUID | ID do QR Code ou `externalId`  |

**Request:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v1/account/53bcb30e-c2df-4316-bbff-161ee01e34be/pix/qrcode/a1b2c3d4-5678-90ab-cdef-1234567890ab' \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
  "type": "cob",
  "status": "PAID",
  "qrCode": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/pc/p/v2/56b07da2bef94006adede26591fcf8b65204000053039865802BR5925NEW COMPANY BANKING 008706009SAO PAULO61080807215562070503***630446CD",
  "amount": 100.00,
  "description": "Pagamento de serviço",
  "expiration": 86400,
  "expiresAt": "2026-03-13T19:16:15.46418",
  "pixKey": "486c486b-ddcd-495a-837a-be52f5989f3e",
  "keyType": "EVP",
  "payerName": "John Doe",
  "payerDocument": "12345678901",
  "recipientName": "John Ham",
  "city": "Sao Paulo",
  "postalCode": "01234567"
}
```

### Campos — Response

| Campo           | Tipo       | Descrição                                                                      |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `id`            | UUID       | ID do QR Code                                                                  |
| `externalId`    | String     | ID de referência do parceiro (se informado)                                    |
| `type`          | String     | Tipo do QR Code: `cob` (cobrança imediata) ou `cobv` (cobrança com vencimento) |
| `status`        | String     | Status atual do QR Code. Ver tabela de status                                  |
| `qrCode`        | String     | Payload do QR Code PIX (EMV)                                                   |
| `amount`        | BigDecimal | Valor em reais. Ex: `100.00`                                                   |
| `description`   | String     | Descrição do pagamento                                                         |
| `expiration`    | Integer    | Tempo de expiração em segundos                                                 |
| `expiresAt`     | String     | Data/hora de expiração (ISO 8601)                                              |
| `pixKey`        | String     | Chave PIX utilizada                                                            |
| `keyType`       | String     | Tipo da chave PIX. Ex: `EVP`, `CPF`, `CNPJ`, `EMAIL`, `PHONE`                  |
| `payerName`     | String     | Nome do pagador (se informado na criação)                                      |
| `payerDocument` | String     | CPF ou CNPJ do pagador (se informado na criação)                               |
| `recipientName` | String     | Nome do recebedor                                                              |
| `city`          | String     | Cidade do recebedor                                                            |
| `postalCode`    | String     | CEP do recebedor                                                               |

**Response — 404 Not Found:**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "PIX QR Code a1b2c3d4-5678-90ab-cdef-1234567890ab not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-03-12T19:16:15Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                  |
| ------------------ | -------------------------- |
| `200 OK`           | QR Code encontrado         |
| `401 Unauthorized` | Token inválido ou expirado |
| `403 Forbidden`    | Sem acesso à conta         |
| `404 Not Found`    | QR Code não encontrado     |

***

## GET /v1/account/{id}/pix/qrcode

Lista os QR Codes PIX de uma conta com paginação. O status de expiração é verificado automaticamente.

**Path Parameters:**

| Parâmetro | Tipo | Descrição                      |
| --------- | ---- | ------------------------------ |
| `id`      | UUID | ID da conta bancária (UUID v4) |

**Query Parameters:**

| Parâmetro  | Tipo    | Obrigatório | Descrição                                                                    |
| ---------- | ------- | ----------- | ---------------------------------------------------------------------------- |
| `pix-type` | String  | Sim         | Tipo do QR Code: `cob` ou `cobv`                                             |
| `page`     | Integer | Não         | Número da página (zero-based). Default: `0`                                  |
| `size`     | Integer | Não         | Itens por página. Default: `20`                                              |
| `sort`     | String  | Não         | Ordenação. Campos permitidos: `createdAt`, `updatedAt`. Ex: `createdAt,desc` |

**Request:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v1/account/53bcb30e-c2df-4316-bbff-161ee01e34be/pix/qrcode?pix-type=cob&page=0&size=10&sort=createdAt,desc' \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "content": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
      "status": "PAID",
      "amount": 100.00,
      "expiresAt": "2026-03-13T19:16:15.46418"
    },
    {
      "id": "b2c3d4e5-6789-01bc-defa-2345678901bc",
      "externalId": null,
      "status": "EXPIRED",
      "amount": 50.00,
      "expiresAt": "2026-03-12T10:00:00.000000"
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    }
  },
  "totalElements": 2,
  "totalPages": 1,
  "last": true,
  "first": true,
  "numberOfElements": 2,
  "empty": false
}
```

### Campos — Objeto do Array `content`

| Campo        | Tipo       | Descrição                                   |
| ------------ | ---------- | ------------------------------------------- |
| `id`         | UUID       | ID do QR Code                               |
| `externalId` | String     | ID de referência do parceiro (se informado) |
| `status`     | String     | Status do QR Code. Ver tabela de status     |
| `amount`     | BigDecimal | Valor em reais. Ex: `100.00`                |
| `expiresAt`  | String     | Data/hora de expiração (ISO 8601)           |

**Status Codes:**

| Status             | Descrição                   |
| ------------------ | --------------------------- |
| `200 OK`           | Lista retornada com sucesso |
| `401 Unauthorized` | Token inválido ou expirado  |
| `403 Forbidden`    | Sem acesso à conta          |
| `404 Not Found`    | Conta não encontrada        |