Via API

Para integrar seu CRM com a Patagon, precisamos que você nos forneça acesso aos dados de leads através de sua API. Esta documentação descreve quais informações necessitamos e como podemos consumi-las do seu sistema.

Ideia-chave: A Patagon precisa buscar (pull) os dados de leads do seu CRM/API para processamento em nossa plataforma.

Como Funciona?

Existem duas formas principais de integração:

• Opção 1 - Push (Cliente envia para Patagon):

  1. Você envia dados de leads para nossos endpoints

  2. Usamos sua API Key para autenticar

  3. Processamos e armazenamos no CRM da Patagon

• Opção 2 - Pull (Patagon busca do cliente):

  1. Você nos fornece acesso à sua API

  2. Consultamos periodicamente novos/atualizados leads

  3. Sincronizamos com nosso sistema

Esta documentação foca nas informações que precisamos receber do seu sistema.

---

_{Para estabelecer a integração, precisaremos que você forneça:}

Informações de Acesso

• Endpoint(s) da sua API (URLs base)

• Credenciais de autenticação (API Key, OAuth, JWT, etc.)

• Documentação da sua API (se disponível)

• Ambiente de homologação (para testes iniciais)

Informações sobre Rate Limits

• Limite de requisições por minuto/hora

• Política de retry em caso de erro

• Horários de manutenção programada (se houver)

Dados de Contato Técnico

• Responsável técnico pelo lado do cliente

• Canal de comunicação para suporte (email, Slack, etc.)

---

Autenticação e Segurança

O Que Suportamos?

A Patagon pode se conectar ao seu sistema usando os seguintes métodos de autenticação:

• Preferencial:

  • Bearer Token (API Key)

  • OAuth 2.0 (Client Credentials ou Authorization Code)

• Também suportamos:

  • Basic Authentication

  • JWT (JSON Web Tokens)

  • Custom Headers

Requisitos de Segurança

Obrigatório: Todas as conexões devem usar HTTPS/TLS para garantir segurança dos dados.

Precisaremos saber:

• Método de autenticação utilizado

• Formato do token/credencial

• Tempo de expiração (se aplicável)

• Processo de renovação de token

Exemplo de Autenticação

Se você utiliza Bearer Token, faremos requisições no formato:

GET https://seu-crm.com/api/v1/leads
Authorization: Bearer {TOKEN_FORNECIDO_POR_VOCÊ}

---

🔗 Endpoints Que Precisamos Consumir

Para uma integração completa, sua API deve disponibilizar os seguintes endpoints:

1. Listar Leads (Obrigatório)

Endpoint para buscar leads, preferencialmente com paginação e filtros por data.

GET /api/v1/leads

Parâmetros esperados (recomendados):

• page ou offset - Para paginação

• limit ou per_page - Quantidade de registros por página

• updated_since - Filtrar leads modificados após data/hora específica

• created_since - Filtrar leads criados após data/hora específica

Exemplo de requisição que faremos:

GET /api/v1/leads?limit=100&updated_since=2025-10-28T00:00:00Z

2. Obter Lead Específico (Recomendado)

Endpoint para buscar detalhes de um lead específico.

GET /api/v1/leads/{lead_id}

3. Webhook para Notificações (Opcional)

Se seu sistema suporta webhooks, podemos receber notificações em tempo real quando:

• Um novo lead é criado

• Um lead existente é atualizado

• Um lead é excluído

Formato esperado:

POST https://api.patagon.ai/webhooks/leads
Content-Type: application/json
{
  "event": "lead.created",
  "timestamp": "2025-10-28T13:20:41Z",
  "data": {
    "id": "lead_123",
    "tf_firstname": "Maria",
    ...
  }
}

Webhooks são opcionais mas recomendados para sincronização em tempo real.

---

🏷️ Mapeamento de Campos

Campos Que Precisamos Receber

Abaixo estão exemplos dos campos que a Patagon precisa consumir do seu CRM. Faremos o mapeamento durante o kickoff técnico.

Campo (Nomenclatura)	Nomenclatura Interna	Tipo	Obrigatório	Descrição
Primeiro Nome	tf_firstname	string	✅	Apenas o primeiro nome do lead
Telefone	phone	string	✅	Telefone de contato (preferencialmente E.164)
Referência/Indicação	tf_referrer	string	❌	Quem indicou o lead
Objetivo/JTBD	rf_objective	enum/string	⚠️	Objetivo principal do lead
Gênero	tf_gender	enum/string	❌	Identificação de gênero
Idade	tf_age	number	❌	Idade em anos (inteiro)

Não se preocupe com nomenclatura! Faremos o mapeamento durante o kickoff. Por exemplo:

• Seu campo first_name → nosso tf_firstname

• Seu campo contact_phone → nosso phone

• Seu campo goal → nosso rf_objective

---

🛠️ Exemplos de Resposta da Sua API

Abaixo estão exemplos de como esperamos que sua API responda.

Exemplo 1: Lista de Leads

Requisição que faremos:

GET /api/v1/leads?limit=2&updated_since=2025-10-28T00:00:00Z
Authorization: Bearer {seu_token}

Resposta esperada (exemplo):

{
  "data": [
    {
      "id": "lead_123",
      "first_name": "Maria",
      "phone": "[phone]",
      "goal": "Ir para a Lua",
      "gender": "Feminino",
      "age": 32,
      "referred_by": "Ana",
      "created_at": "2025-10-28T10:30:00Z",
      "updated_at": "2025-10-28T13:20:41Z"
    },
    {
      "id": "lead_456",
      "first_name": "João",
      "phone": "[phone]",
      "goal": "Outro",
      "gender": null,
      "age": null,
      "referred_by": null,
      "created_at": "2025-10-28T11:15:00Z",
      "updated_at": "2025-10-28T11:15:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 2,
    "next_page": 2
  }
}

Flexibilidade: Seu formato JSON pode ser diferente. O importante é que contenha os dados dos leads e informações de paginação.

Exemplo 2: Lead Individual

Requisição que faremos:

GET /api/v1/leads/lead_123
Authorization: Bearer {seu_token}

Resposta esperada:

{
  "id": "lead_123",
  "first_name": "Maria",
  "phone": "[phone]",
  "goal": "Ir para a Lua",
  "gender": "Feminino",
  "age": 32,
  "referred_by": "Ana",
  "created_at": "2025-10-28T10:30:00Z",
  "updated_at": "2025-10-28T13:20:41Z"
}

---

🚫 Tratamento de Erros

O Que Esperamos da Sua API?

Para uma integração robusta, é importante que sua API retorne códigos HTTP adequados:

Código	Quando Usar	Como Trataremos
200	Requisição bem-sucedida	Processaremos os dados normalmente
400	Parâmetros inválidos	Ajustaremos os parâmetros e tentaremos novamente
401	Falha de autenticação	Alertaremos para renovação de credenciais
404	Recurso não encontrado	Registraremos e pularemos esse item
429	Rate limit excedido	Aguardaremos e tentaremos com backoff exponencial
500-599	Erro no servidor	Retry automático com backoff

---

Dados Sensíveis

A Patagon está em conformidade com LGPD. Todos os dados recebidos são:

• Transmitidos via HTTPS/TLS

• Armazenados com criptografia

• Acessados apenas por sistemas autorizados

• Retidos conforme política de privacidade acordada