Affiliate — Configuração¶

O que é um Affiliate?¶

Um affiliate na iFriend é uma agência de turismo afiliada que comercializa os serviços da iFriend.

Definição¶

Affiliate = Agência: Uma agência de turismo que vende experiências, tours e serviços da iFriend
Pode ter whitelabel: Nem todo affiliate possui whitelabel — é uma relação opcional
Pode ter acesso ao agente: Affiliate com whitelabel pode expor o agente iFriend sob seu próprio domínio

Relação entre conceitos¶

Affiliate (agência)
    │
    ├── pode ter ──────► Whitelabel (domínio próprio)
    │                     │
    │                     └── pode expor ──► Agente iFriend
    │                                         (viaEmbed ou API)
    │
    └── pode ter ──────► Markups de preço
                        (siteMarkupGuide, etc.)

Campos Reais do Affiliate¶

Baseado no código, um affiliate contém os seguintes campos:

Identificação¶

Campo	Tipo	Descrição
`id`	int	ID único do affiliate
`name`	str	Nome da agência
`company`	str	Nome da empresa (jurídico)

Contato¶

Campo	Tipo	Descrição
`phone`	str	Telefone de contato
`emailComercial`	str	Email comercial
`email`	str	Email principal

Endereço¶

Campo	Tipo	Descrição
`address`	str	Endereço linha 1
`address2`	str	Endereço linha 2
`city`	str	Cidade
`state`	str	Estado (UF)
`postcode`	str	CEP
`neighborhood`	str	Bairro

Markups de Preço¶

Campo	Tipo	Descrição
`siteMarkupGuide`	float	Markup para guias (ex: 0.8 = 20% desconto)
`siteMarkupExperience`	float	Markup para experiências
`siteMarkupTicket`	float	Markup para ingressos
`siteMarkupTransfer`	float	Markup para transfers
`siteMarkupPackage`	float	Markup para pacotes

Branding (Emails)¶

Campo	Tipo	Descrição
`logoUrl`	str	URL do logo para emails

Operador (para API)¶

Campo	Tipo	Descrição
`operatorMarkupGuide`	float	Markup operacional guias
`operatorMarkupExperience`	float	Markup operacional experiências
`operatorMarkupTicket`	float	Markup operacional tickets
`operatorMarkupTransfer`	float	Markup operacional transfers
`operatorMarkupPackage`	float	Markup operacional pacotes

Como é identificado¶

Método 1: Via JWT do usuário¶

# GET /affiliates?platformUser.user.userEmail={email}
affiliates = await client.get("/affiliates", {
    "platformUser.user.userEmail": user_email,
    "fields": ["id", "name", "siteMarkupExperience"]
})
affiliate = affiliates[0] if affiliates else None

Método 2: Via partner_code no JWT¶

# JWT contém custom_claims.partner_code
partner_code = jwt_context.get("custom_claims", {}).get("partner_code")

affiliates = await client.get("/affiliates", {
    "partner_code": partner_code,
    "fields": ["id", "name", "logoUrl"]
})

Método 3: Via affiliate_id no message_metadata¶

# SDK JS envia no metadata
affiliate_id = message_metadata.get("affiliate_id")

# Carrega config do affiliate para root_agent
affiliate_config = await AgentBuilder.load_affiliate_config(affiliate_id)
# GET /affiliates/{id}/root_agent

Fluxo de Identificação¶

1. Usuário faz request com JWT
   │
2. Callback injeta affiliate no state
   │ (via platformUser.user.userEmail)
   │
3. Tools buscam dados do affiliate
   │ (markup, logo, contato)
   │
4. Resposta customizada
   │ - Preço com markup
   │ - Email com logo da agência
   │ - WhatsApp da agência

Uso nos Módulos¶

1. precificação (markup de preço)¶

# ifriend_agent/tools/context/enrich_products.py
markup = _get_context_product_markup(affiliate, product)

if markup:
    price = price_net / markup  # Aplica markup

2. Emails (branding)¶

# ifriend_agent/tools/enviar_email_sendgrid_tool.py
logo_url = affiliate.get("logoUrl")
email = affiliate.get("emailComercial")
phone = affiliate.get("phone")

# Template usa logo do affiliate se disponível

3. Suporte (WhatsApp)¶

# ifriend_agent/tools/gerar_formulario_suporte_tool.py
affiliate_id = whitelabel.get("affiliate", {}).get("id")
affiliate = whitelabel.get("affiliate", {})

whatsapp = _resolve_contact_whatsapp() or affiliate.get("phone")

Configuração de Whitelabel (Opcional)¶

Um affiliate pode ter um whitelabel associado:

{
  "id": 123,
  "domain": "agencia.example.com",
  "Affiliate": {
    "id": 456,
    "name": " Agência Exemplo",
    "phone": "+5511999999999"
  }
}

Neste caso: - O whitelabel usa o affiliate para contato - O WhatsApp de suporte vem do affiliate - O dominio é exposed sob a marca do affiliate

Variáveis de Ambiente¶

Variável	Descrição
`ENABLE_WHITELABEL`	Habilita detecção por domínio
`WHITELABEL_DOMAINS`	Domínios permitidos (JSON)

API Reference¶

Listar Affiliates¶

GET /affiliates

Buscar por Email¶

GET /affiliates?platformUser.user.userEmail=email@agencia.com&fields[]=id&fields[]=name

Buscar por ID¶

GET /affiliates/{id}

Buscar Configuração Root Agent¶

GET /affiliates/{id}/root_agent

Diferença: Affiliate vs Whitelabel¶

Aspecto	Affiliate	Whitelabel
O que é	Agência	Domínio próprio
Relação	Entidade principal	Personalização do affiliate
Sempre existe	Sim	Opcional
Exibe agente	Não	Sim (se habilitado)
Domínio	iFriend (theifriend.com)	Próprio (agencia.com)

Resumo¶

Affiliate = agência com dados (nome, contato, markups, logo)
Whitelabel = customização visual (domínio, cores, logo) atrelada ao affiliate
Identificação = via JWT (user email ou partner_code) ou message_metadata (affiliate_id)