Visão Geral
Este documento explica como passar parâmetros na URL do checkout para personalizar o comportamento e capturar informações adicionais durante o processo de pagamento.
Estrutura da URL
Exemplo:
Parâmetros Especiais
1. Grupo de Cliente (group ou grupo)
Descrição: Define o grupo de cliente para aplicar regras específicas, descontos ou configurações personalizadas.
Formato: UUID (Universally Unique Identifier)
Exemplo:
?group=550e8400-e29b-41d4-a716-446655440000
⚠️ Importante:
O valor deve ser um UUID válido do grupo de cliente
Não pode conter espaços ou caracteres especiais
Deve corresponder a um grupo existente no sistema
Formato UUID válido:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
2. Nome do Grupo (cupom ou coupon)
Descrição: Define o grupo de cliente através do nome do grupo (alternativa ao UUID).
Formato: String (nome do grupo)
Exemplo:
?cupom=GRUPOVIP
?coupon=PREMIUM
⚠️ Regras importantes:
Deve ser igual ao nome de um grupo ativo no sistema
Apenas letras e números (sem espaços, hífens, underscores ou caracteres especiais)
Deve corresponder exatamente ao nome de um grupo existente
Se ambos cupom e coupon estiverem presentes, cupom tem prioridade
✅ Exemplos válidos:
cupom=GRUPOVIP
cupom=PREMIUM
cupom=ESTUDANTES
cupom=CORPORATIVO
cupom=VIP2024
❌ Exemplos inválidos:
cupom=GRUPO VIP # Contém espaço
cupom=GRUPO-VIP # Contém hífen
cupom=GRUPO_VIP # Contém underscore
cupom=VIP@2024 # Contém caractere especial
cupom=grupo vip # Contém espaço e minúsculas
Parâmetros Personalizados (Identificadores Internos)
Descrição: Qualquer parâmetro adicional que não seja group, grupo, cupom ou coupon será capturado como identificador interno.
Uso: Estes parâmetros aparecem nos identificadores internos do sistema e podem ser usados para:
Rastreamento de origem
Campanhas de marketing
Identificação de parceiros
Dados analíticos
Informações customizadas
Exemplos:
utm_source=facebook
utm_campaign=natal2024
origem=newsletter
parceiro=empresa_x
campanha=promocao_verao
referrer=site_parceiro
canal=whatsapp
vendedor=joao_silva
Exemplos Práticos
Exemplo 1: Grupo (UUID) + Grupo (Nome)
Resultado:
Grupo de cliente aplicado via UUID
Mesmo grupo referenciado via nome
Nenhum identificador interno
Exemplo 2: Apenas Nome do Grupo + Identificadores
Resultado:
Grupo PREMIUM aplicado via nome
Identificadores internos: utm_source, campanha, vendedor
Exemplo 3: Completo
Resultado:
Grupo VIP aplicado via UUID
Mesmo grupo referenciado via nome (GRUPOVIP)
Identificadores internos: origem, campanha, parceiro, utm_medium
Boas Práticas
✅ Recomendações
Use nomes descritivos para identificadores internos
Mantenha consistência nos nomes dos parâmetros
Teste sempre as URLs antes de usar em produção
❌ Evite
Espaços em qualquer parâmetro
Caracteres especiais desnecessários
Nomes muito longos para parâmetros
Informações sensíveis na URL
Parâmetros duplicados
Limitações
Tamanho da URL: Navegadores têm limite de ~2000 caracteres
Caracteres especiais: Alguns caracteres precisam ser codificados
Espaços: Não são permitidos em nomes de grupos
Processamento no Sistema
Captura: Todos os parâmetros são capturados automaticamente
Limpeza: A URL é limpa, removendo todos os parâmetros
Processamento:
group/grupo → Campo customer_group_uuid (UUID do grupo)
cupom/coupon → Campo cupom (nome do grupo)
Outros parâmetros → Campo metadata (identificadores internos)
Envio: Dados são enviados na API de cobrança, automaticamente