Dados > ChatGPT 5.4 API > CRM

Imagine a cena: você está navegando na internet, encontra um produto incrível para seu pet, clica em "comprar" e... descobre que assinou um plano recorrente sem saber. É como ir ao McDonald's pedir um hambúrguer e sair com um plano de assinatura de Big Macs vitalício.

Na Petvi, esse era o pesadelo diário. Clientes compravam o Condropure sem entender que era uma assinatura recorrente. Outros erravam na escolha do Kit — compravam mais do que precisavam ou menos, como quem vai ao supermercado com fome e compra 10kg de chocolate.

Resultado? Cancelamentos, estornos, e uma equipe de Customer Success que passava mais tempo apagando incêndios do que ajudando clientes.

Criei um formulário pós-assinatura que coleta dados essenciais dos clientes e seus pets. Mas aí vem a pergunta crucial:

"Beleza, Reulison, mas como você organiza esses dados para que façam sentido? E isso vai servir para que?"

A resposta está em duas palavras mágicas: GraphQL e Metadata.

O que é GraphQL?

Imagine que você está em um restaurante. No REST (API tradicional), você pede o "prato completo" e o garçom traz tudo — mesmo que você só queira a batata frita. No GraphQL, você diz: "Quero apenas a batata frita, com sal, e quero saber quantas calorias tem". O garçom volta exatamente com isso.

GraphQL é uma linguagem de consulta que permite pedir exatamente os dados que você precisa. Nada mais, nada menos. Na minha aplicação, usei GraphQL para:

• Buscar pessoas pelo email
• Restaurar pessoas deletadas
• Criar objetos customizados

O que é Metadata?

Metadata é "dados sobre dados". Pense nela como a ficha técnica de um produto. Se você tem um objeto "Pet" no CRM, a Metadata descreve:

• Quais campos ele tem (nome, idade, porte)
• Que tipo de dado cada campo armazena (texto, número, data)
• Como os objetos se relacionam (um tutor pode ter vários pets)

Segundo a documentação do Twenty, a Metadata permite criar Objetos Customizados sem tocar no backend.

"Custom Objects in Twenty are defined through metadata, not code."

Traduzindo: você pode criar novos tipos de dados no CRM sem escrever uma linha de código no backend. É como ter um LEGO onde você pode criar novas peças sem precisar fabricar uma nova fábrica.

Objetos personalizados originam-se de tabelas de metadados que definem a estrutura, o nome e o tipo dos objetos. Todas essas informações estão contidas no banco de dados de esquema de metadados, composto pelas seguintes tabelas:

• DataSource: Detalha onde os dados estão localizados.
• Object: Descreve o objeto e estabelece uma ligação com uma DataSource.
• Field: Define os campos de um Object e conecta-se a ele.

Para adicionar um objeto personalizado, o workspaceMember realiza uma consulta à API /metadata. Isso atualiza os metadados de acordo e gera um esquema GraphQL com base neles, armazenando-o em um cache GQL para uso posterior.

Réulison, desenha pra mim? Claroooooo!

Como os Dados dos Pets se Conectam ao Tutor

Aqui está o coração da aplicação: vincular os dados dos pets ao tutor de forma estruturada.

A Anatomia dos Dados

Sim, vai ter gambiarra com PHP!

// A função que constrói o payload do pet
function buildPetRecordPayload(array $pet, string $personId, array $fieldConfig, array $condicaoMap): array
{
    return [
        'name' => $pet['nome'],              // Nome do pet
        'birthDate' => $pet['birthday'],     // Data de nascimento
        'size' => $pet['porte'],             // Porte (Mini, Pequeno, Médio, Grande)
        'healthCondition' => [$healthValue], // Condição de saúde
        'whyYouUse' => $pet['motivo'],       // Motivo do uso do Condropure
        'firstTimeUsing' => (bool)$pet['primeira_vez_condropure'], // Primeiro uso?
        'age' => (int)$pet['idade'],         // Idade calculada
        'petOnwerId' => $personId,           // CHAVE ESTRANGEIRA: vincula ao tutor
    ];
}

Perceba o campo petOnwerId — é ele que faz a ligação mágica entre o pet e seu tutor. Isso permite que um tutor tenha vários pets e cada pet tenha características específicas.

O Fluxo de Criação

1. Cliente preenche o formulário com dados do tutor e dos pets
2. Sistema busca ou cria o tutor no Twenty CRM
3. Para cada pet, cria um registro vinculado ao tutor via petOnwerId
4. Dados estruturados permitem que agentes de IA entendam hierarquicamente as informações

Por que isso é genial?

Quando os dados estão estruturados hierarquicamente, uma IA consegue:

• Identificar que "God" e "Chico" são pets do mesmo tutor
• Entender que ambos têm condições de saúde específicas
• Recomendar produtos personalizados com base no porte, idade e condição de cada pet

É a diferença entre um atendente de call center que lê um script e um especialista que conhece seu pet pelo nome.

Gerando Prompts Inteligentes

Depois que os dados estão estruturados, o próximo passo é gerar prompts personalizados para cada cliente.

Formatando Dados dos Pets para o Prompt

function formatarDadosPets($pets) {
    $linhas = [];
    foreach ($pets as $index => $pet) {
        $linhas[] = "Pet " . ($index + 1) . ":";
        $linhas[] = "  Nome: " . $pet['name'];
        $linhas[] = "  Idade: " . $pet['age'] . " anos";
        $linhas[] = "  Porte: " . $pet['size'];
        $linhas[] = "  Condições de saúde: " . implode(', ', $pet['healthCondition']);
        $linhas[] = "  Motivo do uso: " . $pet['whyYouUse'];
        $linhas[] = "---";
    }
    return implode("\n", $linhas);
}

Isso gera um prompt como (somente a parte do Pet):

Pet 1:
  Nome: Zé Ninguém
  Idade: 14 anos
  Porte: Pequeno (5–10kg)
  Condições de saúde: Prevenção (pet saudável)
  Motivo do uso: Olha, o Zé é um vira-lata caramelo danado de forte, parece que tem mola nas pernas. Mas eu sempre falo: 'prevenir é melhor que remediar'. Já vi muito cachorro de amigos sofrer de dor nas juntas na velhice e não quero isso pro meu terroristinha. Comecei a dar isso pra ele mesmo novinho, como um 'seguro saúde' pras patinhas. Ele nem percebe, acha que é petisco, e eu durmo tranquila sabendo que tô cuidando do futuro dele. É aquilo: investe agora pra não chorar depois!
---
Pet 2:
  Nome: Freddie
  Idade: 5 anos
  Porte: Pequeno (5–10kg)
  Condições de saúde: Pós-cirurgia ortopédica
  Motivo do uso: Ai, que fase complicada! O Freddie fez a cirurgia do joelho e eu passei um mês inteiro com medo de mexer nele, achando que ia estourar tudo de novo. A recuperação tava lenta, ele só queria ficar deitado, nem o rabinho abanava. Mas depois que comecei com esse protocolo de pós-cirurgia, parece que deu um 'start' nele! Hoje ele já apoia a patinha direitinho e até já quer pular da cama (que susto!). Me deu muita segurança saber que eu tô ajudando ele de verdade nessa recuperação.

O Que Acontece Depois?

1. Os dados do pet e da assinatura são estruturados em JSON
2. Convertidos para texto simples
3. Inseridos em um prompt personalizado
4. A IA gera um e-mail completamente personalizado para cada tutor

Resultado: e-mails que falam sobre "God" e "Chico" pelo nome, mencionam condições específicas, e recomendam o Kit ideal — e não um e-mail genérico "Olá, cliente".

Exemplo e-mails e prompts gerados:

Fernanda

Dados do Usuário:

Retorno do Agente:

recommendedProduct: Recomendo o Condropure para ambos os pets, pois ele oferece suporte articular, saúde da cartilagem e mais mobilidade. Para cães de 5 a 10 kg, a recomendação é de 2 biscoitos por dia para cada pet. O uso é diário e contínuo, e cada pote tem cerca de 66 biscoitos, sendo uma opção prática para manutenção e acompanhamento da saúde articular.
emailSubject: Fernanda, Condropure para Zé Ninguém e Freddie: suporte articular e mobilidade
healhStatus: Zé Ninguém e Freddie estão na faixa de 5 a 10 kg, ambos com necessidade de suporte articular. Freddie encontra-se em pós-cirurgia ortopédica, enquanto Zé Ninguém pode receber o produto como apoio preventivo.
firstTimeOrNot: Como é a primeira vez de uso do Condropure, o ideal é oferecê-lo todos os dias, de forma contínua, seguindo a dosagem conforme o peso do pet. O produto é indicado para suporte articular, saúde da cartilagem e mais mobilidade, podendo ser dado como petisco ou junto da rotina diária.
congratsClient: Fernanda, parabéns pela nova assinatura do Condropure para o Zé Ninguém e o Freddie! Agora eles contam com um suporte diário para as articulações, ajudando na mobilidade, no conforto e na qualidade de vida.
UsoMotivo: O Condropure foi indicado para apoiar a saúde das articulações dos pets. No caso do Zé Ninguém, pode ser usado de forma preventiva, já que o produto também é indicado para pets saudáveis. No caso do Freddie, que está em pós-cirurgia ortopédica, o uso contínuo ajuda no suporte da recuperação e do conforto articular.
depoimento: Uma cliente relatou que, com o uso contínuo do Condropure, percebeu mais disposição e conforto nos movimentos do pet, especialmente em fases de recuperação e cuidado preventivo.

Conteúdo no e-mail:

• Clique para visualizar

Outros e-mails gerados com prompts diferentes:

• Clique para visualizar
• Clique para visualizar

Como o Código Funciona

A função createOrUpdatePerson faz uma busca inteligente:

// Primeiro, tenta encontrar pelo email
$existingPerson = findPersonByEmail($owner['email']);

if ($existingPerson) {
    // Atualiza a pessoa existente
    $result = twentyApiRequest('PATCH', $personEndpoint . '/' . $personId, $personPayload);
} else {
    // Verifica se a pessoa foi deletada
    $deletedPerson = findDeletedPersonByEmail($owner['email']);
    if ($deletedPerson) {
        // Restaura e atualiza
        $restoreResult = restorePersonById($personId);
    } else {
        // Cria nova pessoa
        $result = twentyApiRequest('POST', $personEndpoint, $personPayload);
    }
}

GraphQL em Ação

query FindPersonByEmail($email: String!) {
  people(first: 1, filter: { emails: { primaryEmail: { eq: $email } } }) {
    edges {
      node {
        id
        name { firstName lastName }
        emails { primaryEmail }
      }
    }
  }
}

Se você não entendeu nada até agora, é porque não leu a documentação do GraphQL. Se você entendeu, provavelmente já passou horas debugando uma query que não retornava nada porque esqueceu de pedir o campo id.

E se você é como eu, que usou var_dump() mais vezes do que gostaria de admitir, bem-vindo ao clube. 🍺

Links e Referências

• Site do Produto
• Formulário Pós-Assinatura
• Twenty CRM
• Documentação Twenty (Custom Objects)
• GitHub do Projeto

Outros casos onde esse conceito pode ser usado:

• Concessionárias: vincular carros com motoristas
• Escolas: vinculando dados de filhos com os pais
• SaaS / Software B2B: vinculando funcionários com empresas

Sem objetos customizados, você teria um campo de texto gigante chamado "Observações" onde o atendente colocaria: "Cliente tem 3 pets: Juca, Chico e Xuxu. O Xuxu tem displasia e não consegue mais brincar....."

As IA atuais tem dificuldade de interpretar textos soltos. Ela só entende 100% tudo que está estruturado (JSON/GraphQL).

Com objetos customizados:

1. Filtros avançados: O sistema puxa todos os clientes que têm pets com Displasia E e donos com 2 pets ou mais.
2. Cálculo preditivo: A IA calcula o churn risk baseado no número de objetos filhos (ex: cliente com muitos pets compra mais, então tem menos risco).
3. Hiper-personalização: Você não manda um e-mail sobre "Produto X". Você manda um e-mail sobre "a displasia do Xuxu e a situação pós-cirurgia ortopédica do Juca".

É exatamente isso que transforma um simples formulário de coleta de dados em um motor de orquestração de Customer Success. O código é imortal! 🤓🚀

Conclusão

A integração entre formulários, GraphQL, Metadata e automação de e-mails não é apenas tecnologia — é sobre entender o cliente e fornecer suporte personalizado.

Quando você estrutura dados de pets como objetos vinculados ao tutor, você permite que IAs, sistemas de automação e equipes de Customer Success entendam o contexto completo de cada cliente. E claro, isso é só um exemplo.