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: tem
vencimento, encargos e o mesmo webhook qrcode.paid.
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
Passo 1: Gerar o QR bloqueado
Request
Resposta de Sucesso (201 Created)
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
O path aceita o identifier usado na geração ou o locationId. O body tem os
mesmos termos do QR Code com vencimento:
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)
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 da transação como
qrcode.location_confirm_failed.
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.
Linha do tempo
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
Próximos Passos
- QR Code com vencimento - Cobrança com vencimento emitida de uma vez
- Webhooks - Configurar notificações