Zavora para desarrolladores y agentes de IA

Zavora se opera por programa de tres formas, y las tres pasan por la misma API pública: mismo aislamiento entre cuentas, mismos permisos, mismos topes. No hay una segunda puerta a los datos.

Si llegaste aquí sin conocer el producto, cómo funciona Zavora explica qué hace el agente antes de que lo automatices, y el glosario define los términos que aparecen abajo (ventana de 24 horas, plantilla, BSP).

La API REST

Especificación OpenAPI 3 en /api/v1/openapi.json. Autenticas con Authorization: Bearer zvk_live_… y la llave decide de qué negocio es cada petición.

El primer llamado recomendado es GET /api/v1/me: dice de qué negocio es la llave, qué permisos tiene concedidos, cuáles existen, el plan y los topes. Así sabes qué puedes hacer antes de intentarlo y chocar con un error de permisos.

Los pedidos que entran por el chat —por texto, foto o nota de voz— son los mismos que lees por la API. Lo que se puede hacer hoy: leer y crear pedidos, moverlos (entregado, cancelado, etapa de despacho), leer y editar el catálogo, ajustar inventario con su movimiento registrado, leer y crear compradores, consultar disponibilidad y agendar citas, y escribirle a un comprador por el WhatsApp del negocio.

Las listas van paginadas por cursor, los montos viajan como texto decimal para que ningún centavo se pierda en un float, y las fechas son ISO-8601 en UTC. El tope es de 120 peticiones por minuto por llave.

Los permisos

Cada llave lleva los permisos que le des, y un permiso de escritura no incluye el de lectura. Mover stock va aparte de editar el catálogo, porque es contabilidad y no edición. Y escribirle al comprador por WhatsApp se concede aparte de todo lo demás: esa llave habla con la voz del negocio por su propio número.

Si vas a mandar mensajes, vale la pena entender antes qué permite la WhatsApp Business API y qué cuesta cada mensaje: fuera de la ventana de 24 horas el texto libre no se entrega, y eso no lo decide Zavora.

Si a una llave le falta un permiso, la API responde diciendo cuál. Si el plan pierde el acceso a la API, todas las llaves dejan de funcionar sin que haya que revocar ninguna a mano.

El SDK de Python

pip install zavora

from zavora import Zavora

z = Zavora()                      # lee ZAVORA_API_KEY del entorno
for pedido in z.orders.iter_all(status="paid"):
    print(pedido["id"], pedido["total_amount"])

Cliente síncrono y asíncrono con la misma superficie. iter_all() recorre todas las páginas solo, sin que nadie toque el cursor. Cada cosa que puede salir mal tiene su excepción —SinPermiso, NoEncontrado, Conflicto, TopeAlcanzado— para que nadie compare textos de error a mano.

Los reintentos siguen la regla que importa: se reintenta lo que no cambió nada. Una escritura sin clave de idempotencia nunca se repite, porque si el servidor alcanzó a aplicarla y la respuesta se perdió, repetirla crearía un segundo pedido.

Agentes de IA

El SDK trae las herramientas ya declaradas, en formato de Claude y de OpenAI:

from zavora.agents import ZavoraTools

tools = ZavoraTools(Zavora())
respuesta = claude.messages.create(
    model="claude-opus-5",
    tools=tools.anthropic(),
    messages=[...],
)
resultado = tools.run(nombre, argumentos)

Trece herramientas con descripciones que dicen cuándo usar cada una, que es lo que un modelo necesita para elegir bien. Las que escriben ensayan primero: devuelven lo que harían sin tocar nada, y solo actúan cuando se las llama otra vez con la confirmación. El agente propone, la persona aprueba.

El servidor MCP

Para conectar Zavora a Claude, ChatGPT o Cursor sin escribir código. Se apoya en la misma API pública, así que hereda el aislamiento, los permisos y los topes. Funciona en local para tu propio editor o remoto para un equipo.

La diferencia entre esto y un chatbot de reglas está en agente de IA vs chatbot: un agente decide qué herramienta usar, no sigue un menú.

Webhooks

Zavora avisa a tu sistema cuando pasa algo: se creó un pedido, se pagó, cambió de estado, llegó un comprador nuevo. Los envíos van firmados para que puedas verificar que salieron de Zavora, y se reintentan si tu endpoint no responde.

Probar sin romper nada

Crea una llave de prueba en el panel y úsala igual que una normal. Valida todo contra la base de verdad —las llaves foráneas, la RLS que aísla tu cuenta, el descuento atómico de stock, el tope de tu plan— y no confirma ni un cambio. Tampoco le manda WhatsApp a nadie.

Si lo que necesitas no cabe en la API —un proceso propio, una integración con tu ERP— eso lo construimos como servicio de IA a la medida, y si aún estás decidiendo si te conviene automatizar, está qué cuesta un agente de IA en Colombia.

Un sandbox que no valida contra la base real es peor que no tener sandbox: enseña que algo funciona y después falla en producción. Por eso el modo va en la llave y no escondido en una configuración: quien la ve en un log o en un archivo de entorno sabe de inmediato si está a punto de tocar datos de verdad.