> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Guia de Pix Location

Este guia explica como gerar um QR Code PIX **antes** de saber o valor e o
devedor da cobrança, e liberá-lo para pagamento depois.

## Visão Geral

No Pix Location o QR é gerado **bloqueado**: o código copia e cola já existe e
pode ser impresso, colado num produto ou enviado, mas o pagamento é recusado
até você **confirmar** a cobrança com valor, vencimento e devedor. É indicado
para:

* **Etiquetas e embalagens** - QR impresso antes do pedido existir
* **Comandas e contas** - QR na mesa, valor definido no fechamento
* **Faturas pré-impressas** - Layout pronto, valor fechado depois

Depois de confirmado, o QR se comporta como um
[QR Code com vencimento](/baas/guias/receber/qr-code-com-vencimento): tem
vencimento, encargos e o mesmo webhook `qrcode.paid`.

> **Produto habilitado por tenant**
>
> O Pix Location precisa estar habilitado no seu tenant. Sem a habilitação, a
> geração e a confirmação respondem `403 feature_disabled`. Peça a ativação ao
> time da CorpX.

## Fluxo de Integração

```
┌─────────────┐      ┌──────────────┐      ┌─────────────┐      ┌─────────────┐
│ 1. Gerar QR │      │ 2. Confirmar │      │   Devedor   │      │   Webhook   │
│  bloqueado  │ ───► │   cobrança   │ ───► │   Paga QR   │ ───► │ qrcode.paid │
└─────────────┘      └──────────────┘      └─────────────┘      └─────────────┘
 status BLOCKED        status ACTIVE
```

## Passo 1: Gerar o QR bloqueado

### Request

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/location" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
    "identifier": "mesa-12-noite",
    "message": "Mesa 12"
  }'
```

| Campo        | Tipo   | Obrigatório | Descrição                                                                                                                                                        |
| ------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pixKey`     | string | Sim         | Chave PIX da conta recebedora (deve estar cadastrada)                                                                                                            |
| `identifier` | string | Recomendado | Identificador único (máximo 38 caracteres, charset `[A-Za-z0-9._-]`). Se omitido, a API gera um UUID sem hifens. É por ele que você confirma, consulta e cancela |
| `message`    | string | Não         | Mensagem exibida ao pagador (máximo 140 caracteres)                                                                                                              |

### Resposta de Sucesso (201 Created)

```json
{
  "txid": "mesa-12-noite",
  "emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/9f1c2a7e3b5d4c6e8a0b1c2d3e4f5a6b5204000053039865802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304C3D4",
  "type": "location",
  "status": "BLOCKED",
  "value": 0,
  "message": "Mesa 12",
  "description": "Mesa 12",
  "identifier": "mesa-12-noite",
  "accountId": "{accountId}",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "allowChange": false,
  "locationId": "9f1c2a7e-3b5d-4c6e-8a0b-1c2d3e4f5a6b"
}
```

| Campo        | Descrição                                                                                             |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `emv`        | Código PIX Copia e Cola. Já pode ser impresso; o pagamento é recusado enquanto `status` for `BLOCKED` |
| `status`     | `BLOCKED` até a confirmação                                                                           |
| `locationId` | Identificador do QR no liquidante. Também aceito no lugar do `identifier` na confirmação              |

> **Note**
>
> O `qrcodeId` dos webhooks continua sendo o `txid`. O `locationId` é outro
> identificador e só aparece nas respostas do QR Location.

## Passo 2: Confirmar a cobrança

A confirmação define os termos da cobrança e libera o pagamento.

### Request

```bash
curl -X PUT "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/location/mesa-12-noite/confirm" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 230.40,
    "dueDate": "2026-11-01",
    "debtor": {
      "name": "João Souza",
      "document": "12345678901"
    }
  }'
```

O path aceita o `identifier` usado na geração ou o `locationId`. O body tem os
mesmos termos do [QR Code com vencimento](/baas/guias/receber/qr-code-com-vencimento#parâmetros-do-body):
`value`, `dueDate` e `debtor` obrigatórios; `daysAfterDueDate`, `deduction`,
`discount`, `interest`, `penalty`, `finalValue`, `receiverName` e `message`
opcionais, com as mesmas regras (vencimento em até 365 dias, no máximo 2 casas
decimais). A chave PIX e o `identifier` são sempre os da geração.

### Resposta de Sucesso (200 OK)

```json
{
  "txid": "mesa-12-noite",
  "emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/9f1c2a7e3b5d4c6e8a0b1c2d3e4f5a6b5204000053039865802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304C3D4",
  "type": "location",
  "status": "ACTIVE",
  "value": 230.40,
  "message": "Mesa 12",
  "description": "Mesa 12",
  "identifier": "mesa-12-noite",
  "accountId": "{accountId}",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "allowChange": false,
  "createdAt": "2026-11-01T22:10:00Z",
  "expiresAt": "2026-11-02T02:59:59Z",
  "locationId": "9f1c2a7e-3b5d-4c6e-8a0b-1c2d3e4f5a6b",
  "dueDate": "2026-11-01",
  "daysAfterDueDate": 0,
  "deduction": 0,
  "discount": 0,
  "interest": 0,
  "penalty": 0,
  "finalValue": 230.40,
  "debtor": {
    "name": "João Souza",
    "document": "12345678901"
  },
  "receiverName": "LOJA EXEMPLO"
}
```

O `emv` não muda: é o mesmo QR da geração, agora liberado.

### Quando a confirmação é recusada

Se o liquidante recusar a confirmação, a resposta traz o erro e
`details.qrStatus = "BLOCKED"`: o QR **continua bloqueado** e você pode
confirmar de novo com os dados corrigidos. A recusa também aparece na
[linha do tempo](/baas/guias/conta/timeline) da transação como
`qrcode.location_confirm_failed`.

```json
{
  "errorCode": "partner_rejected",
  "message": "O liquidante recusou a operação.",
  "docs": "https://docs.api.corpx.com/baas/guias/referencia/erros#partner_rejected",
  "details": { "qrStatus": "BLOCKED" }
}
```

Um QR já confirmado, ou com outra confirmação em andamento, não aceita
nova confirmação (`409 invalid_state`). Se o liquidante não responder e não
for possível conferir o estado do QR, o erro vem sem `details.qrStatus`:
consulte o QR antes de confirmar de novo.

## Passo 3: Consultar, cancelar e receber o pagamento

Consulta e cancelamento são os mesmos do QR dinâmico, pelo `identifier`
(`GET .../pix/qr-code/lookup?identifier=` e `DELETE .../pix/qr-code?identifier=`).
Antes da confirmação o lookup devolve `status: "BLOCKED"`.

O pagamento chega como `qrcode.paid` com `data.type = "location"` e
`data.amount` igual ao valor efetivamente pago. Sem pagamento até `expiresAt`,
chega `qrcode.expired`. Veja o
[exemplo de webhook do QR com vencimento](/baas/guias/receber/qr-code-com-vencimento#passo-3-receber-o-webhook).

## Linha do tempo

| Evento                           | Quando                                                     |
| -------------------------------- | ---------------------------------------------------------- |
| `qrcode.location_generated`      | O QR foi gerado bloqueado                                  |
| `qrcode.location_confirm_failed` | A confirmação foi recusada; o QR segue bloqueado           |
| `qrcode.created`                 | A confirmação foi aceita e o QR passou a aceitar pagamento |
| `qrcode.paid`                    | O QR foi pago                                              |

## Permissões

As duas rotas usam o mesmo escopo do QR dinâmico, `qrcode.manage` (ou
`api2/write`). No painel do integrador, gerar e confirmar exigem a permissão
**Emitir QR code com vencimento e Pix Location**.

## Erros Comuns

| `errorCode`          | HTTP | Causa                                                                                                                                    | Solução                                                                      |
| -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `missing_field`      | 400  | `pixKey` ausente na geração; `dueDate`, `debtor` ou o recebedor ausente na confirmação                                                   | Envie os campos obrigatórios                                                 |
| `invalid_document`   | 400  | `debtor.document` sem 11 nem 14 dígitos                                                                                                  | Envie um CPF ou CNPJ válido                                                  |
| `invalid_field`      | 400  | Termos inválidos (ver [QR com vencimento](/baas/guias/receber/qr-code-com-vencimento#erros-comuns)) ou `message` acima de 140 caracteres | Ajuste os termos                                                             |
| `invalid_identifier` | 400  | `identifier` fora do charset ou acima de 38 caracteres                                                                                   | Ajuste o identificador                                                       |
| `feature_disabled`   | 403  | Produto não habilitado no tenant                                                                                                         | Peça a ativação à CorpX                                                      |
| `not_found`          | 404  | Nenhum QR Location com esse `identifier`/`locationId` na conta                                                                           | Verifique o identificador e o accountId                                      |
| `invalid_state`      | 409  | O QR não é Location ou já foi confirmado                                                                                                 | Consulte o QR antes de confirmar                                             |
| `policy_denied`      | 422  | Uma regra de política de QR dinâmico recusou o valor                                                                                     | Veja `violations` — [Políticas e Regras](/baas/guias/autenticacao/politicas) |

## Próximos Passos

* [QR Code com vencimento](/baas/guias/receber/qr-code-com-vencimento) - Cobrança com vencimento emitida de uma vez
* [Webhooks](/baas/guias/conta/webhooks) - Configurar notificações