# Assinaturas Kiwify

## Instalação em uma aplicação existente

1. Faça backup do banco e atualize os arquivos deste pacote.
2. Instale as dependências e aplique a migração (não execute `migrate:fresh` em produção):

```bash
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
```

3. Mantenha o `APP_KEY` existente. Os payloads são cifrados com essa chave. Em uma instalação nova, use `cp .env.example .env` e `php artisan key:generate` uma única vez. A aplicação continua usando PHP 8.3+ e o banco configurado em `.env`.
4. Configure um token não vazio no `.env`, igual ao token do webhook cadastrado na Kiwify:

```dotenv
KIWIFY_WEBHOOK_TOKEN=seu_token_longo_e_aleatorio
KIWIFY_PREVIOUS_WEBHOOK_TOKEN=
```

5. Execute permanentemente um worker dedicado, supervisionado pelo gerenciador de processos do servidor:

```bash
php artisan queue:work billing --queue=billing --sleep=1 --tries=5 --timeout=60 --max-time=3600
```

A conexão `billing` é sempre uma fila de banco, na tabela `jobs` e na mesma conexão padrão da aplicação. Isso independe de `QUEUE_CONNECTION=sync` usado por outros módulos. Não mude essa conexão para outro banco: a transação do recebimento depende dessa atomicidade. O worker deve reiniciar após cada publicação (`php artisan queue:restart`). `retry_after` é 120 segundos, superior ao timeout de 60 segundos. Os intervalos de retry são 10, 60, 300 e 900 segundos. Falhas esgotadas aparecem na administração e em `failed_jobs`.

6. Configure o agendador uma vez por minuto, usando o caminho real da instalação:

```cron
* * * * * cd /caminho/rota-clara && php artisan schedule:run >> /dev/null 2>&1
```

O comando `billing:reconcile` materializa em `app_companies.plan_code` o plano vigente. As verificações de cota também consultam o fim do acesso em tempo real, mesmo se o agendador atrasar. O rebaixamento conserva os dados existentes e aplica os limites gratuitos às próximas operações.

7. No menu **Administração → Planos**, configure os links e os IDs de produto/plano reais. Acesso administrativo usa a permissão global já existente (`is_support_admin`). Para concedê-la a uma conta com e-mail confirmado:

```bash
php artisan support:admin administrador@example.com
```

8. Cadastre na Kiwify a URL HTTPS exata, sem redirecionamento:

```text
https://SEU-DOMINIO/api/webhooks/kiwify
```

Ative os gatilhos `compra_aprovada`, `compra_recusada`, `compra_reembolsada`, `chargeback`, `subscription_renewed`, `subscription_late`, `subscription_canceled`, `pix_gerado` e `boleto_gerado`. Os eventos de Pix e boleto gerados registram apenas a tentativa pendente, sem liberar acesso. Eventos de período grátis e outros eventos ainda não implementados são auditados como `ignored`, sem liberar acesso.

9. Depois de configurar o ambiente, regenere os caches e reinicie os workers:

```bash
php artisan config:cache
php artisan view:cache
php artisan queue:restart
```

## Cadastro e gestão de planos

Rotas administrativas: `/admin/planos` e `/admin/assinaturas`.

A migração cadastra Essencial, Profissional e Ilimitado usando os preços atuais. Os dois planos pagos recebem inicialmente o link solicitado para testes: `https://pay.kiwify.com.br/V4Q1XEb`. Esse mesmo link não distingue planos e não substitui o mapeamento de produto/oferta: antes de vender planos diferentes, cadastre links e IDs correspondentes a cada oferta na Kiwify.

- O ID do produto é `Product.product_id`; o ID do plano é `Subscription.plan.id`. O código curto da URL de checkout não corresponde a esses IDs.
- Um produto com múltiplas ofertas deve ter um ID de plano específico em cada registro. Um mapeamento genérico por produto só é usado quando existe exatamente um candidato. Mapeamento ambíguo gera revisão, sem ativação.
- Nome, descrição, preço de exibição, cotas, passageiros, e-mails, cópias entre empresas, ordem e disponibilidade são editáveis. Preços são inteiros em centavos. `-1` significa cota ilimitada.
- O código de um plano tem até 20 caracteres e é imutável após criação. O plano `starter` permanece gratuito e ativo.
- Desativar remove da vitrine e bloqueia novos checkouts; mantém os assinantes existentes e o histórico. Os planos não são excluídos fisicamente.
- O preço e a recorrência efetivamente cobrados pertencem à Kiwify; editar o preço local não modifica assinaturas externas.
- As definições originais em `config/plans.php` fornecem cotas iniciais. Ao salvar um plano no administrativo, as cotas persistidas passam a prevalecer. Planos já contratados usam as configurações atuais desse registro.
- O comando `plans:set` serve para empresas sem histórico Kiwify, inclusive códigos cadastrados na administração. Empresas com histórico Kiwify têm o plano controlado pelos períodos de acesso.

## Checkout e associação segura

Os botões **Assinar** abrem um modal Bootstrap acessível, com aviso do ambiente seguro da Kiwify, empresa e e-mail usados na compra. Visitantes entram na conta e selecionam uma empresa antes do checkout. Apenas administradores da empresa, com e-mail confirmado, podem contratar.

A confirmação é um POST protegido por sessão/CSRF e valida o contexto `_company`. O servidor só redireciona para HTTPS em `pay.kiwify.com.br`, sem credenciais, porta ou fragmento. O URL é lido do cadastro, nunca de uma URL fornecida pelo navegador.

O checkout cria uma referência UUID opaca com usuário, empresa, plano e e-mail. Ela segue no parâmetro oficial `sck=rc_UUID`, junto ao preenchimento de `name` e `email`. A primeira associação exige produto/plano mapeados, referência correspondente e mesmo e-mail da compra. A referência vale para compras iniciadas em até 72 horas; entregas atrasadas continuam elegíveis pela data de criação do pedido. Uma referência consumida por uma assinatura não pode vincular outra. Renovações usam o `subscription_id` já conhecido, sem depender dos parâmetros de rastreamento ou do e-mail atual. Tentativas recusadas que omitem `Subscription` podem usar a referência de checkout já vinculada ou o pedido previamente conhecido, sem retirar o acesso pago.

Não se associa uma compra a uma empresa apenas pelo e-mail: a mesma pessoa pode administrar várias empresas. Compras externas sem referência são guardadas para revisão, sem conceder acesso. Para compras feitas fora desse fluxo, será necessário implementar uma conciliação administrativa explícita; o pacote não tenta adivinhar a empresa.

Uma assinatura em cobrança já conhecida (`active`, `past_due` ou `pending`) impede outro checkout para a mesma empresa. A troca de plano é feita cancelando a assinatura anterior na Kiwify e contratando outra oferta. O cancelamento externo não é chamado por API neste pacote.

## Recebimento, autenticidade e idempotência

- Endpoint: `POST /api/webhooks/kiwify`. Não usa sessão nem CSRF. A Kiwify adiciona `?signature=...` à URL.
- A assinatura é HMAC-SHA1 hexadecimal minúsculo dos bytes originais, com o token como chave. A comparação usa `hash_equals`. Não existe bypass por token simples no corpo/header. Token ausente retorna 503; assinatura inválida, 401; JSON inválido, 422; corpo acima de 1 MiB, 413.
- Uma transação grava o evento e o job na fila. Só depois do commit responde 202. Se o banco ou a inserção da fila falharem, a transação é revertida e a entrega não é confirmada, permitindo reenvio da Kiwify.
- A chave única é o SHA-256 do provedor, `order_id` e tipo normalizado de evento. Sem pedido, usa `subscription_id` ou hash do corpo para auditoria. Não inclui timestamps de entrega. Reenvios incrementam `received_count`/`last_received_at`, preservam o payload original e não geram outra linha/job.
- Tipos diferentes para o mesmo pedido têm linhas de evento separadas, mas `billing_payments.provider_order_id` é único: compra aprovada e renovação do mesmo pedido representam um só pagamento.
- O processamento bloqueia as linhas de evento, empresa, assinatura e pagamento; status final não é reaplicado. Alterações de cotas e assinatura compartilham o bloqueio da empresa. Um savepoint impede efeitos parciais em erros de domínio.
- O histórico mantém eventos válidos mesmo sem produto, usuário ou referência reconhecidos. Assinatura inválida e JSON ilegível não armazenam payload financeiro como evento autenticado.

## Estados e valores

| Evento recebido | Assinatura | Pagamento |
| --- | --- | --- |
| `order_approved`, `subscription_renewed` com pedido `paid` | Ativa, pelo período informado | Pago |
| `order_rejected` | Não retira período já pago | Recusado |
| `subscription_late` | Atrasada; respeita o acesso informado e o período pago | Recusado apenas se o pedido estiver `refused`; não inventa pagamento aprovado |
| `subscription_canceled` | Cancelada, conserva período pago | Não cria cobrança; registra estorno se o pedido vier estornado |
| `order_refunded` | Reembolsada, sem acesso | Reembolsado |
| `chargeback` | Chargeback, sem acesso, mesmo com `customer_access.has_access=true` | Chargeback |
| `pix_created`, `billet_created` | Não libera plano | Pendente |

Cancelamento com pedido `refunded`/`chargedback` é tratado como reversão financeira. Acesso usa `Subscription.customer_access.access_until` e `has_access`, com fallback para `Subscription.next_payment` nos JSONs antigos anexados. Não se concede acesso pago indefinido se o término estiver ausente. Um evento antigo não reativa um reembolso/chargeback; um ciclo anterior não encurta o período mais recente. Cancelar uma assinatura antiga não retira o plano de outra assinatura vigente da mesma empresa.

Os valores vêm de `Commissions.charge_amount`, em centavos, com moeda separada. Não se usa `my_commission` nem `charges.completed.amount` como valor bruto cobrado. Datas na raiz são interpretadas em Brasília e datas de `Subscription` em UTC; o banco armazena UTC e a interface mostra Brasília. `approved_date` é usado como data de pagamento quando disponível.

## Histórico e operação

Tabelas: `billing_plans`, `billing_checkouts`, `billing_subscriptions`, `billing_webhook_events`, `billing_payments`.

Os payloads originais são cifrados pelo cast `encrypted` do Laravel. Os campos de auditoria, datas, valores e status são consultáveis. Não armazene tokens nas URLs configuradas, no código ou em logs. Preserve `APP_KEY` e as chaves anteriores durante rotações. A tabela `failed_jobs` contém somente o ID do evento serializado no job, sem copiar o payload.

Estados de processamento: `pending`, `processed`, `needs_attention`, `ignored`, `failed`. A administração mostra recebimentos, tentativas, resultado, payload, filtros por status/referência e reprocessamento de falhas. Corrija primeiro a causa indicada (mapeamento, referência, e-mail, valor ou datas). Reprocessar é outra transação que grava `pending` junto a um job. Payloads históricos permanecem intactos. Repetições já processadas não alteram o estado.

A visão financeira agrupa por moeda: receita de pagamentos ainda pagos (sem descontar taxas), reembolsos e chargebacks em separado. Não subtrai o mesmo estorno duas vezes e não mistura BRL com outras moedas. Não representa saldo disponível para saque nem MRR contábil. A contagem de assinaturas por status e de períodos com acesso vigente é apresentada separadamente.

O painel **Meu plano** exibe assinatura, período e histórico de pagamentos; os pagamentos são visíveis apenas aos administradores da empresa. A visão geral mostra um resumo da assinatura sem dados pessoais de cobrança. A exclusão local de usuário/empresa não cancela cobranças externas: o cancelamento deve ocorrer na Kiwify. As referências locais de cobrança ficam nulas quando a conta/empresa é excluída; o histórico financeiro e o payload cifrado são preservados para o operador aplicar sua política de retenção.

## Testes e verificação antes de operar

```bash
composer install
php artisan test
php artisan route:list --path=api/webhooks/kiwify -v
```

Resultado da verificação em PHP 8.4 e SQLite: **112 testes, 1.659 asserções, zero falhas ou erros** (26 testes específicos de Kiwify e 86 testes existentes). A sintaxe dos 25 arquivos PHP alterados/adicionados e o cache de templates também foram verificados.

Os fixtures sanitizados em `tests/Fixtures/kiwify` derivam dos cinco anexos. `KiwifyBillingTest` cobre assinatura de bytes originais, rotação de token, fila real em banco, rollback do recebimento, deduplicação de evento/pagamento, ciclos, atraso, recusa, cancelamento, expiração, estorno antes de aprovação, chargeback, eventos fora de ordem, falhas de associação, permissões, separação entre empresas, CRUD e segurança do URL. O teste injeta a referência de checkout e o mapeamento exigidos; os anexos originais não possuem essa referência.

Use **Testar Webhook** da Kiwify para conferir assinatura e entrega. Esses dados têm IDs fictícios e não devem ativar automaticamente contas reais. Faça a validação completa de checkout, `sck`, oferta e eventos usando uma compra controlada: a Kiwify não oferece sandbox para essa operação. Este pacote não executa compras, não solicita reembolsos reais e não configura sua conta Kiwify.

A verificação automatizada deste pacote usa SQLite. A renderização das páginas foi verificada pelos testes HTTP; a abertura visual em navegador não pôde ser executada neste ambiente. Valide os fluxos concorrentes também no banco de produção e confirme o funcionamento contínuo de worker/agendador antes de liberar vendas.

Documentação oficial consultada:

- https://docs.kiwify.com.br/api-reference/webhooks/receiving
- https://docs.kiwify.com.br/api-reference/webhooks/subscription-events
- https://ajuda.kiwify.com.br/pt-br/article/como-preencher-os-campos-do-checkout-pela-url-de7ezo/
- https://ajuda.kiwify.com.br/pt-br/article/como-passar-parametros-de-rastreamento-na-url-do-checkout-src-utm-tags-entre-outros-1spiptc/
