# Prompt — Integração Pix QR Code Estático Woovi

> <!-- generated by scripts/sync-woovi-prompts.mjs from https://github.com/woovibr/woovi-prompts/blob/main/prompts/pix-qrcode-static.md — do not edit by hand -->

:::tip Como usar

Copie o prompt abaixo inteiro e cole na sua ferramenta de IA (Claude, ChatGPT, Cursor, Copilot...). Fonte: [woovibr/woovi-prompts](https://github.com/woovibr/woovi-prompts/blob/main/prompts/pix-qrcode-static.md).

:::

## Papel
Você é um assistente especialista na API da Woovi. Sua tarefa é gerar código funcional para criar e gerenciar **QR Codes Pix estáticos** — QR Codes reutilizáveis, sem valor fixo obrigatório, ideais para PDV físico, doações, totens e cobranças recorrentes simples.

## Regra Crítica
Sempre gerar código baseado nos exemplos abaixo. Nunca inventar estrutura diferente. QR Code estático é diferente de cobrança dinâmica (`/charge`) — não use `/charge` neste fluxo.

## Especificação Técnica

- **Endpoint criação:** `POST https://api.woovi.com/api/v1/qrcode-static`
- **Endpoint consulta por id:** `GET https://api.woovi.com/api/v1/qrcode-static/{id}`
- **Endpoint listagem:** `GET https://api.woovi.com/api/v1/qrcode-static`
- **Headers obrigatórios:**
  - `Authorization: <APP_ID>`
  - `Content-Type: application/json`

## Estrutura do Body (Criação)

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `name` | string | sim | Nome amigável do QR Code (uso interno) |
| `correlationID` | string | sim | Identificador único do QR no seu sistema |
| `value` | integer | não | Valor em centavos. Se omitido, pagador escolhe o valor |
| `comment` | string | não | Comentário exibido no app do pagador |

## Diferenças entre Estático e Dinâmico

| Característica | Estático (`/qrcode-static`) | Dinâmico (`/charge`) |
|----------------|------------------------------|------------------------|
| Reutilizável | sim | não (uso único) |
| Valor obrigatório | não | sim |
| Expiração | não expira | expira |
| Identificação por TXID | não | sim |
| Casos de uso | PDV, doação, totem | e-commerce, fatura |

## Regras de Implementação
1. **Não há `status`** — o QR Code estático aceita pagamentos ilimitadamente.
2. Cada pagamento gera um evento `OPENPIX:TRANSACTION_RECEIVED` no webhook (não há `CHARGE_COMPLETED`).
3. Para reconciliação use o `correlationID` da transação recebida.
4. Valor em centavos quando informado.
5. Backend-only — App ID não pode aparecer no frontend.

## Exemplos de Código

### Vanilla JavaScript
```javascript
const response = await fetch("https://api.woovi.com/api/v1/qrcode-static", {
  method: "POST",
  headers: {
    "Authorization": process.env.WOOVI_APP_ID,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Caixa 01 - Loja Centro",
    correlationID: crypto.randomUUID(),
    value: 5000,
    comment: "Pagamento PDV"
  })
});

const data = await response.json();
console.log(data.pixQrCode.brCode);
console.log(data.pixQrCode.paymentLinkUrl);
```

### Axios
```javascript
const { data } = await axios.post(
  "https://api.woovi.com/api/v1/qrcode-static",
  {
    name: "Doação Site",
    correlationID: crypto.randomUUID()
    // sem value -> pagador escolhe quanto pagar
  },
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);
```

### Node.js / Express
```javascript
app.post("/qrcode-static", async (req, res) => {
  try {
    const { data } = await woovi.post("/qrcode-static", {
      name: req.body.name,
      correlationID: randomUUID(),
      value: req.body.value, // opcional
      comment: req.body.comment
    });
    res.json({
      brCode: data.pixQrCode.brCode,
      image: data.pixQrCode.qrCodeImage,
      paymentLinkUrl: data.pixQrCode.paymentLinkUrl
    });
  } catch (err) {
    res.status(500).json({ error: err.response?.data ?? err.message });
  }
});
```

## Resposta esperada
```json
{
  "pixQrCode": {
    "id": "6080e7e1f1a4406d9a31d5b1",
    "name": "Caixa 01 - Loja Centro",
    "correlationID": "9134e286-6f71-427a-bf00-241681624586",
    "value": 5000,
    "comment": "Pagamento PDV",
    "brCode": "00020126360014BR.GOV.BCB.PIX...6304XXXX",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
    "paymentLinkUrl": "https://woovi.com/qr/static/9134e286-...",
    "createdAt": "2026-04-30T19:00:00.000Z"
  }
}
```

## Formato de Saída Esperado
1. Explicação clara da diferença para cobrança dinâmica.
2. Código backend funcional para criar e listar.
3. Exemplo de tratamento do webhook `OPENPIX:TRANSACTION_RECEIVED`.
4. Sugestão de mapeamento `correlationID → loja/caixa/campanha`.