kobra-python

SDK oficial en Python para Kobra — motor de cobranza conversacional con WhatsApp.

Instalación

Mientras no esté publicado en PyPI, se instala directo desde GitHub:

pip install git+https://github.com/Remora-IA/kobra-python.git

Quickstart

from kobra import Kobra
from kobra.api.cobranzas import iniciar_cobranza_api_sdk_cobranzas_post
from kobra.models import IniciarCobranzaRequest

# Tu API key se genera en https://kobra.remora-ia.com/panel
kobra = Kobra(api_key="kbr_...")

# Iniciar una cobranza — Carolina arranca el contacto y reporta por webhook
resp = iniciar_cobranza_api_sdk_cobranzas_post.sync(
    client=kobra,
    body=IniciarCobranzaRequest(
        deudor_id="SR-12345",
        nombre="Juan Pérez",
        telefono="+56912345678",
        monto=150000,
        concepto="Cuota octubre",
    ),
)

print(resp.conversation_id)   # ID único de la conversación en Kobra
print(resp.link_pago)         # URL del portal del deudor
print(resp.primer_mensaje)    # texto que Carolina envió por WhatsApp

La API key también se lee del entorno:

import os
os.environ["KOBRA_API_KEY"] = "kbr_..."

from kobra import Kobra
kobra = Kobra()

Endpoints disponibles

El SDK envuelve los endpoints de la API SDK de Kobra. Solo se listan funciones que existen hoy — si necesitás algo que no está, abrí un issue:

Tag	Funciones disponibles	Verbos HTTP
kobra.api.cobranzas	iniciar_cobranza_*, listar_cobranzas_*, obtener_cobranza_*, cancelar_cobranza_*, iniciar_cobranzas_bulk_*	POST · GET · GET · POST · POST
kobra.api.webhooks	registrar_webhook_* (PUT idempotente — sobreescribe el config existente)	PUT
kobra.api.pasarelas	registrar_zafepay_creds_* (registra credenciales ZafePay BYO de tu tenant)	PUT
kobra.api.sistema	sdk_status_* (health-check sin auth)	GET

Notas honestas para el dev integrador:

• Un único webhook por organización. Si necesitás multi-webhook (uno para cobrado, otro para no_responde), por ahora hacé dispatch en tu propio endpoint. Multi-webhook está en el roadmap.
• No hay listar ni eliminar webhooks todavía. Para reemplazar la URL/eventos, llamá de nuevo a registrar_webhook_* con la config nueva (es PUT, sobreescribe).
• Pasarelas: hoy solo ZafePay (BYO — tus credenciales caen directo en tu cuenta). MercadoPago + Khipu corren desde el backend de Kobra (no hace falta config en el SDK).

Cada función expone variantes .sync(), .sync_detailed(), .asyncio(), .asyncio_detailed() — la versión _detailed devuelve Response[T] con status_code, content, headers y parsed.

Bulk — para vencimientos mensuales

from kobra import Kobra
from kobra.api.cobranzas import iniciar_cobranzas_bulk_api_sdk_cobranzas_bulk_post
from kobra.models import CobranzasBulkRequest, IniciarCobranzaRequest

kobra = Kobra(api_key="kbr_...")

batch = iniciar_cobranzas_bulk_api_sdk_cobranzas_bulk_post.sync(
    client=kobra,
    body=CobranzasBulkRequest(
        cobranzas=[
            IniciarCobranzaRequest(
                deudor_id=str(d.id),
                nombre=d.nombre,
                telefono=d.telefono,
                monto=d.monto,
                concepto=f"Cuota {d.mes}",
            )
            for d in deudores_atrasados
        ],
    ),
)
print(f"Iniciadas: {batch.iniciadas}")
print(f"Duplicadas (ya estaban activas): {batch.duplicadas}")
print(f"Errores: {batch.errores}")

Webhooks

Cuando una cobranza cambia de estado (deudor pagó, acordó, no responde), Kobra dispara un webhook firmado con HMAC. Para verificar la firma:

import hmac, hashlib

def verify_webhook(body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header.replace("sha256=", ""))

Doc completa de eventos y payloads: kobra.docs.buildwithfern.com/empezar/verificar-webhooks

Tipado

El SDK incluye py.typed. Los requests son modelos attrs tipados — autocompleta en VS Code / PyCharm para los IniciarCobranzaRequest, CobranzasBulkRequest, etc.

Heads-up sobre response models (v0.5.x): los response models (ResponseIniciarCobranzaApiSdkCobranzasPost, etc.) actualmente exponen los campos vía additional_properties porque el schema de response del backend está en migración a Pydantic. En esta versión, accedé así:

resp = iniciar_cobranza_api_sdk_cobranzas_post.sync(client=kobra, body=req)
# Acceso al dict subyacente — el IDE no autocompleta todavía:
conversation_id = resp.additional_properties["conversation_id"]
link_pago       = resp.additional_properties["link_pago"]
primer_mensaje  = resp.additional_properties["primer_mensaje"]

En v0.6.0 los campos van a estar declarados con tipado completo. Tracking: GitHub issue #1.

Async

Cada función generada tiene variante async:

import asyncio
from kobra import Kobra
from kobra.api.cobranzas import listar_cobranzas_api_sdk_cobranzas_get

async def main():
    kobra = Kobra(api_key="kbr_...")
    async with kobra as client:
        resp = await listar_cobranzas_api_sdk_cobranzas_get.asyncio(client=client, limite=100)
        return resp

asyncio.run(main())

Soporte

• Quickstart: kobra.docs.buildwithfern.com/empezar/quickstart
• Verificar webhooks: kobra.docs.buildwithfern.com/empezar/verificar-webhooks
• Portal (panel + tu API key): kobra.remora-ia.com/panel
• Backend: kobra.remora-ia.com
• Issues: github.com/Remora-IA/kobra-python/issues

Licencia

MIT — ver LICENSE.