Guia de Parâmetros da URL no Link de Contratação | Central de Ajuda Base de Clientes

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

https://portal.clientbase.com.br/checkout/[UUID_DO_LINK]?[PARAMETROS]

Exemplo:

https://portal.clientbase.com.br/checkout/b2e9695c-f5de-46d9-b967-af90308f6f76?group=550e8400-e29b-41d4-a716-446655440000&cupom=VENDEDORX&utm_source=facebook&campanha=natal2024

Parâmetros Especiais

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
Atenção!
- 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
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

Atenção!
- 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.
  Atenção!
  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
- 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úscula

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

Novos parâmetros suportados (Informações do Cliente):

Esses parâmetros permitem pré-preencher automaticamente os dados do cliente no checkout, reduzindo o atrito e acelerando a conversão.

Todos são opcionais.

Parâmetro	Descrição
name	Nome do cliente
email	E-mail do cliente
doc	CPF ou CNPJ (somente números)
phone	Telefone (DDD + número, somente números ou formatação simples)
cep	CEP do cliente
city	Cidade
neighborhood	Bairro
street	Logradouro / Rua
address_number	Número da casa, prédio ou apartamento
complement	Complemento do endereço

Exemplo completo com preenchimento automático:

https://portal.clientbase.com.br/checkout/UUID?name=Maria+Souza&[email protected]&doc=12345678900&phone=41999887766&cep=80010000&city=Curitiba&neighborhood=Centro&street=Rua+XV+de+Novembro&address_number=100&complement=Apto+12

Atenção!

O parâmetro doc deve conter CPF/CNPJ sem pontos ou hífens;
name permite espaços (automático via encoding);
Todos os demais seguem formatação simples (não exigimos máscaras padrão);
Caso o usuário edite qualquer campo no checkout, o valor do parâmetro é substituído pelo valor digitado.

Exemplos Práticos

Exemplo: Grupo (UUID) + Grupo (Nome)

https://portal.clientbase.com.br/checkout/UUID?group=550e8400-e29b-41d4-a716-446655440000&cupom=GRUPOVIP

Resultado:
- Grupo de cliente aplicado via UUID;
- Mesmo grupo referenciado via nome;
- Nenhum identificador interno.
Exemplo: Apenas Nome do Grupo + Identificadores

https://portal.clientbase.com.br/checkout/UUID?cupom=PREMIUM&utm_source=facebook&campanha=natal&vendedor=maria

Resultado:
- Grupo PREMIUM aplicado via nome;
- Identificadores internos: utm_source, campanha, vendedor.
Exemplo 3: Completo

https://portal.clientbase.com.br/checkout/UUID?group=550e8400-e29b-41d4-a716-446655440000&cupom=GRUPOVIP&origem=email&campanha=black_friday&parceiro=loja_abc&utm_medium=email

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