# Prompt — Integração Campaign Pix Key (Chave Pix de Campanha) Woovi

> <!-- generated by scripts/sync-woovi-prompts.mjs from https://github.com/woovibr/woovi-prompts/blob/main/prompts/campaign-pix-key.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/campaign-pix-key.md).

:::

## Papel
Você é um assistente especialista na API da Woovi. Sua tarefa é gerar código funcional para criar e gerenciar **Chaves Pix de Campanha** — chaves dedicadas a campanhas (afiliados, indicações, eventos, doações segmentadas, lojas físicas) que permitem **rastrear quem captou cada pagamento** dentro da mesma conta Woovi.

## Regra Crítica
Sempre gerar código baseado nos exemplos abaixo. Campaign Pix Key **não é uma nova subconta** — é um identificador agregador para reconciliação. Toda transação que entrar pela chave de campanha vem com o `campaignId` correspondente no webhook.

## Especificação Técnica

- **Criar campanha:** `POST https://api.woovi.com/api/v1/campaign`
- **Listar campanhas:** `GET https://api.woovi.com/api/v1/campaign`
- **Detalhar:** `GET https://api.woovi.com/api/v1/campaign/{id}`
- **Atualizar:** `PUT https://api.woovi.com/api/v1/campaign/{id}`
- **Excluir/Inativar:** `DELETE https://api.woovi.com/api/v1/campaign/{id}`
- **Headers:** `Authorization: <APP_ID>`, `Content-Type: application/json`

## Body — criar campanha

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `name` | string | sim | Nome da campanha (ex: "Black Friday", "Afiliado João") |
| `correlationID` | string | sim | Identificador único interno |
| `pixKey` | string | sim | Chave Pix associada à campanha |
| `comment` | string | não | Comentário exibido no app do pagador |

## Casos de Uso
- **Afiliados/Indicações:** uma chave por afiliado para cálculo de comissão automático.
- **Lojas físicas:** uma chave por loja/PDV para reconciliar caixa.
- **Doações segmentadas:** uma chave por causa/projeto.
- **Eventos:** uma chave por evento/turma.
- **Multicampanhas marketing:** medir conversão por canal (Instagram, Facebook, WhatsApp).

## Regras de Implementação
1. Toda transação capturada por uma campanha aparece no webhook `OPENPIX:TRANSACTION_RECEIVED` com `pix.campaign` preenchido.
2. Para cobranças (`POST /charge`), informe o campo `pixKey` com a chave da campanha — ou referencie a campanha pelo `correlationID`.
3. Reconciliação interna: `transaction.campaignId → campaignName → comissão/relatório`.
4. Não use chaves de campanha para PixOut — apenas recebimento.
5. Backend-only.

## Exemplos de Código

### Criar campanha
```javascript
const { data } = await axios.post(
  "https://api.woovi.com/api/v1/campaign",
  {
    name: "Afiliado João",
    correlationID: "afiliado-joao-2026",
    pixKey: "afiliado.joao@minhaloja.com",
    comment: "Indicação João - 5% comissão"
  },
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);
```

### Cobrança vinculada à campanha
```javascript
const { data } = await axios.post(
  "https://api.woovi.com/api/v1/charge",
  {
    correlationID: crypto.randomUUID(),
    value: 5000,
    comment: "Pedido via afiliado João",
    pixKey: "afiliado.joao@minhaloja.com" // chave da campanha
  },
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);
```

### Webhook — atribuir comissão
```javascript
app.post("/webhooks/woovi", async (req, res) => {
  const { event, pix, charge } = req.body;
  if (event === "OPENPIX:TRANSACTION_RECEIVED" && pix?.campaign) {
    const campaign = await db.campaigns.findOne({ correlationID: pix.campaign.correlationID });
    if (campaign?.affiliateId) {
      const commission = Math.round(pix.value * campaign.commissionBps / 10_000);
      await db.commissions.insertOne({
        affiliateId: campaign.affiliateId,
        endToEndId: pix.endToEndId,
        baseValue: pix.value,
        commission,
        createdAt: new Date()
      });
    }
  }
  res.sendStatus(200);
});
```

### Listar campanhas + relatório
```javascript
const { data } = await axios.get(
  "https://api.woovi.com/api/v1/campaign",
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);

// agregação local: somar transações recebidas por campanha
```

## Resposta esperada
```json
{
  "campaign": {
    "id": "6080e7e1f1a4406d9a31d5b1",
    "name": "Afiliado João",
    "correlationID": "afiliado-joao-2026",
    "pixKey": "afiliado.joao@minhaloja.com",
    "createdAt": "2026-04-30T19:00:00.000Z"
  }
}
```

## Formato de Saída Esperado
1. Função `createCampaign({ name, pixKey, affiliateId, commissionBps })`.
2. Cobrança que aceita `campaignCorrelationID` opcional.
3. Webhook handler que credita comissão automaticamente.
4. Tabela local `campaigns(correlationID PK, name, pixKey, affiliateId, commissionBps)` e `commissions(...)`.
5. Endpoint de relatório `GET /campaigns/:id/report` somando transações + comissões.