Guías

Patrones completos para las integraciones más frecuentes. Los ejemplos están en curl; para el detalle de cada endpoint en otros lenguajes, consulta la Referencia de API.

Onboarding automático de un cliente

Da de alta un cliente nuevo desde tu plataforma, de punta a punta. Los pasos 1-4 son por API; la conexión del canal es manual.

BASE="https://api.overtaker.online/api/v1"
KEY="sk_live_xxx"

# 1. Crear el tenant
TENANT=$(curl -s -X POST "$BASE/partner/tenants" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Cliente Nuevo", "email": "admin@cliente.com", "plan_id": "starter", "bot_name": "Sofia" }')
TENANT_ID=$(echo "$TENANT" | jq -r '.tenant_id')

# 2. Asignar rol del bot
ROLE_ID=$(curl -s "$BASE/partner/roles" -H "Authorization: Bearer $KEY" | jq -r '.[0].id')
curl -s -X PUT "$BASE/partner/tenants/$TENANT_ID/bot-config/role" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{ \"bot_role_id\": \"$ROLE_ID\" }"

# 3. Cargar conocimiento inicial
curl -s -X POST "$BASE/partner/tenants/$TENANT_ID/kb/answers" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "entries": [ { "question": "¿Qué horarios tienen?", "answer": "Lunes a viernes 9-18h." } ] }'

# 4. Verificar estado
curl -s "$BASE/partner/tenants/$TENANT_ID/health" -H "Authorization: Bearer $KEY" | jq

Después de esto, entregá las credenciales de admin al cliente para conectar su canal. Hacé polling a /health hasta que channel_connected sea true.

Editar los datos de un cliente

Actualizá el nombre de la organización o el email del admin de un tenant ya creado con PATCH /partner/tenants/{tenant_id}. Ambos campos son opcionales: mandá solo el que quieras cambiar.

curl -X PATCH "$BASE/partner/tenants/$TENANT_ID" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Nuevo Nombre S.A.", "admin_email": "nuevo-admin@cliente.com" }'

Cambiar el admin_email cierra la sesión del admin

Al modificar admin_email, Overtaker invalida todos los JWT vigentes de ese usuario admin (incrementa su token_version). El admin del tenant tendrá que volver a iniciar sesión en el panel con el nuevo email. Cambiar solo el name no afecta las sesiones. Avisá al cliente antes de cambiarle el email.

Leer la configuración actual del bot

Antes de editar la config de un agente —o para clonar ajustes entre clientes— leé la config vigente con GET /partner/tenants/{tenant_id}/bot-config (el PUT del Quickstart solo la escribe).

curl "$BASE/partner/tenants/$TENANT_ID/bot-config" -H "Authorization: Bearer $KEY" | jq

Devuelve el tone, openai_model, session_timeout_hours, bot_memory_size, bot_role_id y la version/status actuales del bot.

Sincronizar tu CRM con webhooks

Reacciona en tu sistema cada vez que se captura o avanza un lead en cualquiera de tus tenants.

# 1. Registrar el webhook (una vez)
curl -X POST "$BASE/partner/webhooks" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://tucrm.com/hooks/overtaker",
    "events": ["lead.created", "lead.stage_changed", "tenant.limit_warning"]
  }'

En tu endpoint receptor:

1. Verificá la firma X-Overtaker-Signature con tu webhook_secret (cómo).
2. Usá X-Overtaker-Delivery como clave de idempotencia (descartá entregas repetidas).
3. Respondé 2xx rápido y procesá en background — si tardás, Overtaker reintenta.

@app.post("/hooks/overtaker")
async def receive(request: Request):
    raw = await request.body()
    if not verify_webhook(raw, request.headers["X-Overtaker-Signature"], SECRET):
        return Response(status_code=401)
    event = json.loads(raw)
    delivery_id = request.headers["X-Overtaker-Delivery"]
    if already_processed(delivery_id):       # idempotencia
        return Response(status_code=200)
    enqueue(event)                            # procesar async
    return Response(status_code=200)

Carga masiva de FAQs

Para importar el catálogo de conocimiento de un cliente, agrupá las preguntas en lotes en vez de una llamada por FAQ (cada request cuenta contra el rate limit).

curl -X POST "$BASE/partner/tenants/$TENANT_ID/kb/answers" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "question": "¿Hacen envíos?", "answer": "Sí, a todo el país." },
      { "question": "¿Métodos de pago?", "answer": "Tarjeta, transferencia y efectivo." },
      { "question": "¿Tienen garantía?", "answer": "12 meses en todos los productos." }
    ]
  }'

• El endpoint acepta hasta 200 entradas por request. Para catálogos más grandes, dividí en lotes de 200 y serializá las llamadas.
• Para documentos largos (PDF, DOCX), usá POST /kb/documents en lugar de kb/answers — el contenido se procesa en background.

Suspender y reactivar un cliente

Cuando un cliente deja de pagar, suspendé su tenant (no se borran datos) y reactivalo cuando regularice.

# Suspender
curl -X DELETE "$BASE/partner/tenants/$TENANT_ID" -H "Authorization: Bearer $KEY"

# Reactivar
curl -X POST "$BASE/partner/tenants/$TENANT_ID/reactivate" -H "Authorization: Bearer $KEY"

Consultar tu cuenta de partner

GET /partner/me devuelve un resumen de tu cuenta de reseller: datos del partner y el conteo de tenants (activos / suspendidos / totales). Sirve para armar el encabezado de tu dashboard o, simplemente, para validar que tu API key es correcta.

curl "$BASE/partner/me" -H "Authorization: Bearer $KEY" | jq

{
  "partner_id": "tenant_partner123",
  "name": "Tu Empresa",
  "plan_id": "reseller",
  "api_key_prefix": "sk_live_abcd",
  "tenants": { "total": 12, "active": 10, "suspended": 2 }
}

Conciliar facturación mensual

Obtené el consumo de cada tenant para cruzarlo con tu propia facturación.

curl "$BASE/partner/billing?period=2026-06" -H "Authorization: Bearer $KEY" | jq

Devuelve, por tenant: plan, conversaciones usadas, overage y costo estimado del período.