REF-901-07: SolidAffiliate Integration
ADR: ADR-901 — IntegrationsEscopo: Hooks consumidos, AffiliateAdapter bridge, AffiliateService, API v1 endpoints, Entitlement AFL
0. Affiliate Domain Contract
SolidAffiliate é a fonte de verdade para dados de afiliados. middag-account não persiste entidade Affiliate própria — usa o AffiliateAdapter como projeção read-only das tabelas do SolidAffiliate.
Campos projetados via AffiliateAdapter (lidos, não persistidos):
| Campo | Tipo | Fonte |
|---|---|---|
affiliate_id | int | solid_affiliate_affiliates.id |
organization_id | int | Resolvido via user_id → Organization |
status | string | solid_affiliate_affiliates.status (pending/approved/rejected) |
referral_code | string | solid_affiliate_affiliates.referral_code |
commission_rate | decimal | solid_affiliate_affiliates.commission_rate |
total_earned | decimal | Calculado de solid_affiliate_referrals |
Invariante: middag-account NUNCA escreve nas tabelas do SolidAffiliate.
Único dado persistido pelo middag-account: Entitlement classe AFL criado via hook solid_affiliate/affiliate/approved (ver §5 abaixo).
Lifecycle de status: Determinado pelo SolidAffiliate. middag-account reage via hooks (§1) — não gerencia o lifecycle diretamente.
1. Hooks Consumidos
O SolidAffiliate é plugin WordPress de terceiros para o Programa de Parceiros. middag-account integra via WP hooks. SolidAffiliate é fonte de verdade para dados de afiliados.
| Hook | Quando | Ação no middag-account |
|---|---|---|
solid_affiliate/referral/created | Nova indicação registrada | Captura order_id, affiliate_id, commission |
solid_affiliate/referral/status_changed | Status muda (pending→approved→paid) | Atualiza dados de referral locais |
solid_affiliate/affiliate/registered | Novo afiliado se registra | Log para auditoria |
solid_affiliate/affiliate/approved | Afiliado aprovado | Cria Entitlement classe AFL (AFL-{YYYY}{MM}{SEQ:4d}) |
solid_affiliate/payout/completed | Pagamento processado | Atualiza histórico de payouts |
2. AffiliateAdapter Bridge
Middag\Account\Integration\Affiliate\
AffiliateAdapterInterface.php — contrato
SolidAffiliateAdapter.php — implementação (lê tabelas do SolidAffiliate)O adapter lê diretamente das tabelas do SolidAffiliate. CRITICO: não duplicar dados — tabelas do SolidAffiliate são fonte de verdade. Único dado persistido pelo middag-account é o Entitlement AFL.
3. AffiliateService
Middag\Account\Domain\Affiliate\AffiliateService:
| Método | Retorno |
|---|---|
getAffiliateProfile($organizationId) | Perfil: nome, email, status, link referral |
getReferrals($organizationId, $filters) | Lista de indicações com paginação |
getCommissionSummary($organizationId) | Totais: ganho, pendente, pago |
getPayoutHistory($organizationId) | Registros de pagamentos |
4. API v1 Endpoints
| Endpoint | Método | Descrição |
|---|---|---|
/middag-account/v1/affiliates/profile | GET | Perfil do afiliado |
/middag-account/v1/affiliates/referrals | GET | Lista de indicações (filtro por status) |
/middag-account/v1/affiliates/commissions | GET | Resumo de comissões |
/middag-account/v1/affiliates/payouts | GET | Histórico de pagamentos |
/middag-account/v1/affiliates/register | POST | Solicitar registro como afiliado |
5. Entitlement AFL
Cada afiliado aprovado recebe Entitlement classe AFL. Criado automaticamente pelo hook solid_affiliate/affiliate/approved. Vincula conta de afiliado ao sistema de Entitlement unificado (ADR-202).