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.

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"

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.