Pesquisa — Documentação Interna: CRMBonus

Data: 2026-05-15
Contexto: Task #193232 — Análise do fluxo de integração CRMBonus
Fontes:

• coezzion-service-checkout/docs/crm/crm_analise.md
• Wiki Azure DevOps — ZZAPPS.wiki: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Arquitetura e Serviços/Integração CRM&Bonus
• Wiki Azure DevOps — ZZAPPS.wiki: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Fluxo de Captura de Transação - Pagar.me
• Wiki Azure DevOps — ZZAPPS.wiki: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Processos/Cancelamento manual em caso de status 81 (pagar.me)
• Wiki Azure DevOps — ZZAPPS.wiki: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Processos/Pagamento dois cartões - PagarMe

---

Fonte 1: docs/crm/crm_analise.md (doc interna da API Checkout)

Resumo

Documento descreve a integração CrmBonusService com os três métodos principais: DebitCrmBonusAsync, CancelCrmBonusAsync e FinishCrmBonusAsync.

Pontos cobertos

• A validação de resposta é feita pelo método IsCrmBonusValidResponse: HTTP 2xx e "status": true no body JSON.
• URL base configurada em Apis:CrmBonus:BaseURL.
• DebitCrmBonusAsync → {BaseURL}/baixa_bonus — chamado em CreatePaymentCommandHandler.
• CancelCrmBonusAsync → {BaseURL}/cancelarBonusEcom — chamado por: OrderCommandHandler, AntiFraudWebhookService, PagarMeCaptureService, PagarMeRefundService.
• FinishCrmBonusAsync → {BaseURL}/finaliza_compra — chamado por PosCaptureService, que por sua vez é usado por: WebhookBraspagService, AntiFraudWebhookService, PagarMeCaptureService, PagarMeCreditCardService, PagarMePixService, FinishPaymentService.

Semântica de used_bonus documentada

Valor	Cenário descrito
true	Cancelamento pós-finalização: estorno (PagarMeRefundService) ou cancelamento após aprovação antifraude (AntiFraudWebhookService)
false	Cancelamento pré-finalização: antifraude recusou (AntiFraudWebhookService) ou captura falhou (PagarMeCaptureService)

Nota de inconsistência: A análise de código real mostra que AntiFraudWebhookService envia used_bonus = true apenas no fluxo Braspag com falha de captura — não no cenário de recusa do antifraude. O documento interno descreve um comportamento que não está implementado como descrito.

---

Fonte 2: Wiki ZZAPPS — Integração CRM&Bonus

Path: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Arquitetura e Serviços/Integração CRM&Bonus

Contexto arquitetural

A integração foi implementada originalmente nos Lambdas AWS do ZZLink. O documento descreve o fluxo do ponto de vista do sistema integrador (ZZLink), que é o canal que envia as informações de bônus para o checkout.

Ambientes (Lambdas)

Ambiente	IDs Lambda
Teste/Homologação	3vxcnib5b7, nwr5thvbki
Produção	zu67cy2pr1

Autenticação — detalhe importante

• Homologação: credenciais fixas em código.
• Produção: a propriedade codEmpresa é lida da tabela ZZLINK_LOJA, coluna PGTOC_CRMBONUS_CODEMPRESA.
• A hash armazenada no banco já está em Base64 — não deve ser convertida novamente ao inserir.
• Se PGTOC_CRMBONUS_CODEMPRESA for null para a loja, o objeto crmBonus deve ser enviado como null — nenhuma integração CRM é executada.

Criação do link (zzApp → ZZLink)

O App da vendedora consulta o endpoint consulta_bonus do CRM&Bonus diretamente (fora do ZZLink). O ZZLink apenas recebe os dados já calculados no payload do createByZzApp:

{
    "vlLink": 439.9,
    "attendance": {...},
    "crmBonus": {
        "user_id": 26951808,
        "valor_bruto": 439.9,
        "bonus_resgatado": 23.78,
        "ids_bonus": "7444497"
    }
}

Os dados são serializados e persistidos na coluna ZZLP_CRMBONUS_JSON da tabela ZZLINK_PEDIDO.

Na criação do link, se bonus_resgatado > 0, o bônus é reservado via baixa_bonus.

Aprovação de pedidos (gatilhos para finaliza_compra)

Conforme a Wiki, os eventos que disparam finaliza_compra são:

1. Aprovação pela análise antifraude (webhook)
2. Pagamento por cliente fidelizado (finishOrder)
3. Aprovação automática (approvePaymentAutomatically)
4. Confirmação de pagamento via Pix (webhook)

Cancelamento (gatilhos para cancelarBonusEcom)

Conforme a Wiki, os eventos que disparam cancelarBonusEcom são:

1. Cancelamento ou estorno (reversePayment)
2. Job de expiração de pedidos (JobExpiredOrders)

Exibição do bônus no checkout

O getInfo do ZZLink retorna o objeto payment com os valores de bônus:

{
    "payment": {
        "fullValue": 499.8,
        "discount": 199.8,
        "crmBonus": 40.0,
        "valueToPay": 260.0
    }
}

O campo crmBonus sempre é retornado — vale 0 quando não há bônus utilizado.

---

Fonte 3: Wiki ZZAPPS — Cancelamento manual status 81 (pagar.me)

Path: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Processos/Cancelamento manual em caso de status 81 (pagar.me)

Ponto relevante

"Este processo não contempla a liberação de CRMBonus utilizado, visto que os casos analisados não utilizaram desconto por CRMBonus."

Isso indica que o processo de cancelamento manual do status 81 (ErrorAntifraud) não inclui cancelamento de bônus CRM como etapa padrão. O processo exige verificação manual prévia se CRMBonus foi utilizado.

---

Fonte 4: Wiki ZZAPPS — Fluxo de Captura de Transação Pagar.me

Path: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Fluxo-de-Captura-de-Transação - Pagar.me

Referências ao CRMBonus encontradas via busca

A Wiki documenta que após a captura, o PosCaptureService chama o CRM&Bonus com FinishCrmBonusAsync, usando o DTO:

crmBonus = CrmBonutDTO.CreateFromCrmBonus(
    userId: cart.CrmBonus.UserId,
    total: cart.CrmBonus.Total,
    rescuedBonus: cart.CrmBonus.RescuedBonus,
    idsBonus: cart.CrmBonus.IdsBonus,
    paymentId: paymentIdComplex,
    generateBonus: cart.GenerateCrmBonus
)

---

Fonte 5: Wiki ZZAPPS — Pagamento dois cartões (PagarMe)

Path: /PRODUTOS DIGITAIS/INFORMAÇÕES TÉCNICAS/Processos/Pagamento dois cartões - PagarMe

Fluxograma relevante

A Wiki documenta o fluxo com antifraude e CRMBonus explicitamente:

ClearSale Webhook / zzportal Aprovar Manual
    └── API Checkout
        └── Pedido APROVADO?
            ├── SIM → Captura PagarMe
            │        └── Capturado?
            │            ├── SIM → PosCaptura → CRMBonus / PDV / Email
            │            └── NÃO → Refund → PosRefund → CRMBonus
            └── NÃO → Refund → PosRefund → CRMBonus

Isso confirma que para o fluxo de dois cartões PagarMe:

• No cancelamento (antifraude reprovado ou falha de captura), o cancelamento do bônus passa pelo PosRefundService, não diretamente pelo AntiFraudWebhookService.