QR Codes impressos

QR Code estático para imprimir (balcão, caixa, mesa). Reutilizável, com valor fixo ou digitado pelo pagador. Os Pix feitos por ele são reconhecidos pelo txid do QR e chegam como pagamentos matched com static_qr_id.

Criar QR Code impresso

POST /v1/static_qrs

Gera o BR Code estático com a chave Pix padrão da unidade e um txid próprio (até 25 caracteres) e devolve poster_url, a página do cartaz pronta para imprimir. Requer o escopo charges:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

Campo	Tipo	Descrição
`label` obrigatório	string	Nome interno do ponto (ex.: "Caixa 1").
`description`	string	Texto que aparece no app do pagador (infoAdicional).
`amount`	string (valor)	Valor fixo; sem ele, o pagador digita o valor.
`metadata`	Metadata	Até 20 pares chave/valor livres do integrador (chave ≤ 40, valor ≤ 500 caracteres). Não use para dados pessoais.

Respostas

201 QR criado.
400 Requisição inválida (formato ou campos).
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/static_qrs" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Caixa 1",
  "description": "Loja Aurora - Centro"
}'

Identificador nos logs: api.static_qrs.create

Listar QR Codes impressos

GET /v1/static_qrs

Requer o escopo charges:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`limit`	consulta	integer
`starting_after`	consulta	string	Cursor — ID do último objeto da página anterior.
`ending_before`	consulta	string	Cursor — ID do primeiro objeto da página seguinte.

Respostas

200 Lista paginada.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/static_qrs?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.static_qrs.list

Consultar QR Code impresso

GET /v1/static_qrs/{static_qr_id}

Inclui quantos pagamentos o QR recebeu e o total. Requer charges:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`static_qr_id` obrigatório	caminho	string

Respostas

200 QR.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/static_qrs/sq_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.static_qrs.retrieve

Desativar QR Code impresso

POST /v1/static_qrs/{static_qr_id}/deactivate

Use quando o cartaz for trocado ou extraviado. Pix que ainda chegarem por ele viram pagamentos unmatched (motivo static_qr_inactive), com o prazo de decisão de sempre. Requer charges:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

Nome	Onde	Tipo	Descrição
`static_qr_id` obrigatório	caminho	string

Respostas

200 QR desativado.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/static_qrs/sq_01J9Z3F0A1B2C3D4E5F6G7H8J9/deactivate" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.static_qrs.deactivate