Via API

Para integrar tu CRM con Patagon, necesitamos que nos proporciones acceso a los datos de leads a través de tu API. Esta documentación describe qué información necesitamos y cómo podemos consumirla desde tu sistema.

Idea clave: Patagon necesita extraer (pull) los datos de leads desde tu CRM/API para procesarlos en nuestra plataforma.

¿Cómo Funciona?

Existen dos formas principales de integración:

🔹 Opción 1 — Push (el cliente envía a Patagon)

1. Tú envías los datos de leads a nuestros endpoints

2. Utilizamos tu API Key para autenticar

3. Procesamos y almacenamos la información en el CRM de Patagon

---

🔹 Opción 2 — Pull (Patagon consulta al cliente)

1. Nos proporcionas acceso a tu API

2. Consultamos periódicamente leads nuevos o actualizados

3. Sincronizamos todo con nuestro sistema

Esta documentación se centra en los datos que necesitamos recibir de tu sistema.

---

Para establecer la integración, necesitaremos que nos envíes:

Información de Acceso

• Endpoints de tu API (URLs base)

• Credenciales de autenticación (API Key, OAuth, JWT, etc.)

• Documentación técnica de la API (si está disponible)

• Ambiente de homologación / sandbox para pruebas iniciales

Información sobre Rate Limits

• Límite de solicitudes por minuto/hora

• Política de retry en caso de error

• Horarios de mantenimiento planificado (si existen)

Datos de Contacto Técnico

• Responsable técnico por parte del cliente

• Canal de comunicación para soporte (email, Slack, etc.)

---

Autenticación y Seguridad

¿Qué soportamos?

Patagon puede conectarse a tu sistema con los siguientes métodos:

Preferidos:

• Bearer Token (API Key)

• OAuth 2.0 (Client Credentials o Authorization Code)

También compatible con:

• Basic Authentication

• JWT

• Custom Headers

Requisitos de Seguridad

Obligatorio: Todas las conexiones deben usar HTTPS/TLS para garantizar seguridad de los datos.

Necesitaremos saber:

• Método de autenticación

• Formato del token/credencial

• Tiempo de expiración (si aplica)

• Proceso de renovación del token

Ejemplo de Autenticación (Bearer Token)

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

---

🔗 Endpoints que Necesitamos Consumir

1. Listar Leads (Obligatorio)

Endpoint principal para recuperar leads, idealmente con paginación y filtros por fecha:

GET /api/v1/leads

Parámetros recomendados:

• page / offset

• limit / per_page

• updated_since

• created_since

Ejemplo de consulta que realizaremos:

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

2. Obtener Lead Individual (Recomendado)

GET /api/v1/leads/{lead_id}

3. Webhooks (Opcional, pero recomendado)

Para datos en tiempo real:

• lead creado

• lead actualizado

• lead eliminado

Ejemplo:

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"
  }
}

Los webhooks son opcionales, pero aceleran muchísimo la sincronización.

---

🏷️ Mapeo de Campos

Campos requeridos por Patagon

A continuación se presentan ejemplos de los campos que Patagon necesita consumir desde tu CRM. El mapeo completo se realizará durante el kickoff técnico.

Campo (Nomenclatura)	Nomenclatura Interna	Tipo	Obligatorio	Descripción
Primer Nombre	tf_firstname	string	✅	Solo el primer nombre del lead
Teléfono	phone	string	✅	Teléfono de contacto (preferentemente en formato E.164)
Referencia / Indicación	tf_referrer	string	❌	Quién recomendó o refirió al lead
Objetivo / JTBD	rf_objective	enum/string	⚠️	Objetivo principal del lead
Género	tf_gender	enum/string	❌	Identificación de género
Edad	tf_age	number	❌	Edad en años (entero)

No te preocupes por la nomenclatura. Haremos el mapeo durante el kickoff. Por ejemplo:

Tu campo first_name → nuestro tf_firstname Tu campo contact_phone → nuestro phone Tu campo goal → nuestro rf_objective

---

🛠️ Ejemplos de Respuesta de tu API

A continuación se muestran ejemplos de cómo esperamos que tu API responda.

Ejemplo 1: Lista de Leads

Solicitud que realizaremos:

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

Respuesta esperada (ejemplo):

{
  "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
  }
}

Flexibilidad: Tu formato JSON puede ser diferente. Lo importante es que incluya los datos de los leads y la información de paginación.

Ejemplo 2: Lead Individual

Solicitud que realizaremos:

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

Respuesta esperada (ejemplo):

{
  "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"
}

---

🚫 Manejo de Errores

¿Qué Esperamos de tu API?

Para una integración robusta, es importante que tu API devuelva códigos HTTP adecuados:

Código	Cuándo Usarlo	Cómo lo Trataremos
200	Solicitud exitosa	Procesaremos los datos normalmente
400	Parámetros inválidos	Ajustaremos los parámetros y lo intentaremos nuevamente
401	Fallo de autenticación	Alertaremos para la renovación de credenciales
404	Recurso no encontrado	Registraremos el evento y continuaremos
429	Rate limit excedido	Esperaremos y reintentaremos con backoff exponencial
500–599	Error del servidor	Reintento automático con backoff

---

Datos Sensibles

Patagon cumple con la LGPD. Todos los datos recibidos son:

• Transmitidos vía HTTPS/TLS

• Almacenados con cifrado

• Accedidos únicamente por sistemas autorizados

• Retenidos según la política de privacidad acordada

---

❓ FAQ – Preguntas Frecuentes

¿Con qué frecuencia Patagon consultará nuestra API?

Esto se definirá durante el kickoff técnico, generalmente entre 5 y 30 minutos, respetando tus rate limits.

¿Almacenan todos los datos o solo referencias?

Almacenamos únicamente los campos mapeados necesarios para procesarlos en nuestro CRM. Los detalles se revisarán durante la reunión de kickoff.

¿Qué ocurre si nuestra API se cae o queda indisponible?

Contamos con un sistema de reintentos automáticos y alertas. En cuanto tu API vuelva a estar disponible, la sincronización se restablece automáticamente.

¿Necesitamos desarrollar una API desde cero?

No. Si tu CRM ya cuenta con una API, probablemente podremos conectarnos directamente. En caso contrario, evaluaremos alternativas como webhooks, iPaaS u otras soluciones viables.

¿Cuánto tiempo tarda la integración?

Generalmente entre 1 y 2 semanas después del kickoff técnico, dependiendo de la complejidad.