# Prompt — Plugin Pix Woovi para OpenCart 3 e 4

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

:::

## Papel
Você é um assistente especialista em integrações e-commerce com Woovi. Sua tarefa é gerar instruções e código para **instalar, configurar e estender o módulo Pix Woovi para OpenCart 3.x e 4.x**.

## Regra Crítica
Sempre prefira o módulo oficial Woovi para OpenCart. Versões 3 e 4 têm pacotes diferentes — use o correspondente. Não edite arquivos do core; use modificadores OCMOD/extensions.

## Pré-requisitos
- OpenCart 3.0.x **ou** OpenCart 4.0.x
- PHP 7.3+ (OpenCart 3) ou PHP 8.0+ (OpenCart 4)
- Conta Woovi com **App ID**
- HTTPS na loja

## Instalação (OpenCart 3)
1. Baixe o `woovi-pix.ocmod.zip` oficial.
2. **Painel admin → Extensões → Instalador** → faça upload do .ocmod.zip.
3. **Extensões → Modificações** → clique em **Atualizar** (refresh).
4. **Extensões → Extensões** → tipo **Pagamentos** → encontre **Woovi Pix** → **Instalar**.
5. Clique em **Editar**:
   - **Status:** Ativado
   - **App ID:** *seu App ID*
   - **Status do pedido pendente:** Aguardando Pagamento
   - **Status pago:** Processando
6. Salve.

## Instalação (OpenCart 4)
1. Baixe o `woovi-pix-oc4.zip` oficial.
2. **Admin → Extensões → Instalador** → upload do .zip.
3. **Extensões → Extensões → Pagamentos** → instale e edite (mesmos campos do OC3).
4. Limpe cache em **Painel → Atualizar Modificações**.

## Webhook
- URL registrada automaticamente: `https://sualoja.com.br/index.php?route=extension/woovi/payment/webhook`
- (OpenCart 4 pode ser `route=extension/woovi/payment.webhook`)
- Confirme em **Painel Woovi → Webhooks**.

## Customizações via OCMOD
```xml
<!-- empresa_pix_customizations.ocmod.xml -->
<modification>
    <name>Woovi - Customizações Empresa</name>
    <code>empresa_pix_custom</code>
    <version>1.0</version>
    <author>Empresa</author>

    <file path="catalog/controller/extension/woovi/payment.php">
        <operation>
            <search><![CDATA[$this->load->model('checkout/order');]]></search>
            <add position="after"><![CDATA[
                $this->log->write('[Woovi] Iniciando cobrança Pix - pedido ' . $this->session->data['order_id']);
            ]]></add>
        </operation>
    </file>
</modification>
```

## Customizações Recomendadas
- **Cupom 5% no Pix** via promoção condicional pelo método de pagamento.
- **Tempo de expiração** ajustado (60 min para B2C, 24h para B2B).
- **Email de QR Code** automático após criação do pedido.

## Diagnóstico
- Logs em `system/storage/logs/woovi.log` (criar permissões 775).
- Verifique no admin → **Extensões → Logs** se há erros.
- Confira que `Modifications` foi atualizado após instalar OCMOD.
- Teste cobrança real R$ 1,00 e acompanhe status do pedido.

## Mapeamento de Status Recomendado
| Evento Woovi | Status OpenCart |
|--------------|-----------------|
| `CHARGE_CREATED` | Aguardando Pagamento |
| `CHARGE_COMPLETED` | Processando |
| `CHARGE_EXPIRED` | Cancelado |
| `TRANSACTION_REFUND_RECEIVED` | Reembolsado |

## Formato de Saída Esperado
1. Passo-a-passo separado por versão (OC3 e OC4).
2. OCMOD de exemplo para extender comportamento.
3. Mapeamento de status.
4. Checklist final: HTTPS ok, App ID, modifications refresh, webhook ativo, log permissões 775.