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": "+5511999999999",
      "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": "+5511988885555",
      "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": "+5511999999999",
  "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

AnteriorVia ApiDeck PróximoAPI

Atualizado há 19 dias