Todo lo que el negocio hace por WhatsApp se puede hacer por programa: leer y crear pedidos, mover el despacho, editar el catálogo, ajustar inventario, agendar citas y escribirle al comprador. Una sola API pública detrás de tres formas de usarla.
● 200 OKRateLimit-Remaining: 119zvk_test_ · nada se guarda
>>> from zavora import Zavora>>> z = Zavora() # lee ZAVORA_API_KEY>>> for p in z.orders.iter_all(status="paid"):... print(p["id"][:8], p["total_amount"])
⚙ zavora · resumen_del_negocio◆ Zavora · así va tu negocioPedidos recientes analizados: 38 • pagado: 21 • entregado: 12 • pendiente: 5Vendido (pagado/entregado): $4.812.300 COPProductos con 5 o menos en stock: 2
● MCPClaude · Cursordatos de ejemplo
19endpoints en la API REST v1
17herramientas en el servidor MCP
11permisos, uno por cosa que se puede hacer
120peticiones por minuto por llave
Una sola API
Tres formas de entrar. Una sola puerta a tus datos.
La API REST, el SDK de Python y el servidor MCP pasan por la misma API pública: mismo aislamiento entre cuentas, mismos permisos, mismos topes. No hay un camino privilegiado a la base.
API RESTcURL · ERPSDK Pythonpronto en PyPIMCPClaude · CursorAPI pública v1llave · permisos · topesPedidosCatálogoInventarioCompradoresCitasWhatsApp
El servidor MCP le da a tu asistente de IA las herramientas de Zavora. Pregunta cómo va el día, qué falta despachar o qué se está agotando, y pídele que actúe: cada escritura llega primero como ensayo para que una persona la apruebe.
1
Crea una llave de prueba
Panel → Integraciones → API y webhooks. Elige Prueba y los permisos que quieras darle a la IA.
2
Conecta tu cliente
Una línea en la terminal o un bloque de JSON, según dónde trabajes.
3
Pregúntale
«¿Cómo vamos hoy?», «¿qué pedidos faltan por despachar?», «crea el pedido de Don Carlos».
# Versión alojada (ChatGPT y clientes web): próximamente.
# Hoy, en acceso anticipado, en tu propio servidor con HTTPS delante:
docker build -t zavora-mcp /ruta/a/zavora-mcp
docker run -p 8000:8000 zavora-mcp
# En el cliente remoto, registra la URL con /mcp al final
# y la llave en la cabecera Authorization:
# https://tu-servidor.com/mcp
# Authorization: Bearer zvk_live_…
MCP local (stdio) hoy; versión alojada próximamente. El paquete zavora-mcp está en acceso anticipado. Escríbenos por WhatsApp y te lo compartimos para conectarlo. En modo remoto el servidor no guarda llaves: cada petición trae la suya.
Tu asistente de IA conectado a Zavora por MCP
¿Cómo vamos hoy?
zavora · resumen_del_negociolectura✓
◆ Zavora · así va tu negocioPedidos recientes analizados: 38 · pagados 21 · entregados 12 · pendientes 5. Vendido: $4.812.300 COP. Dos productos con 5 o menos en stock: te sugiero reponer el arroz antes del viernes.
Crea un pedido de 10 bultos de Arroz Diana para Tienda Don Carlos.
zavora · crear_pedido confirmar=falseensayo✓
◆ Zavora · revisa antes de crear (aún no se ha creado nada)• 10 × Arroz Diana 5 kg — $21.900 COP c/u (stock 46) El total final lo calcula Zavora con los precios del catálogo.
AprobarCancelar
zavora · crear_pedido confirmar=trueescritura✓
◆ Zavora · pedido creado ✓Total $219.000 COP · estado confirmado. ¿Le aviso a Don Carlos por WhatsApp que ya va en camino?
Ejemplo ilustrativo con datos de prueba. Así responde el servidor real: firma ◆ Zavora, cifras sacadas de la API y ensayo antes de cada escritura.
Herramientas MCP
17 herramientas que dicen cuándo usarlas.
Cada descripción le explica al modelo cuándo elegirla, no solo qué hace. Las de lectura se marcan como seguras e idempotentes; las de escritura, como acciones que piden confirmación.
quien_soy
De qué negocio es la llave, qué permisos tiene y si está en modo prueba. La primera llamada.
lectura
resumen_del_negocio
Pedidos por estado, lo vendido y lo que se está agotando. Para «¿cómo vamos?».
lectura
listar_productos
El catálogo del negocio, más recientes primero, paginado por cursor.
lectura
ver_producto
Precio, stock, SKU y descripción de un producto.
lectura
listar_pedidos
Pedidos por estado. Sin filtro deja por fuera los carritos.
lectura
ver_pedido
Un pedido con sus líneas, total, entrega y fecha de pago.
lectura
listar_clientes
Compradores con su WhatsApp, etapa y consentimiento de marketing.
lectura
ver_cliente
Un comprador por su id.
lectura
disponibilidad
Franjas libres de un día, en la hora local del negocio.
lectura
crear_pedido
Con precios del catálogo y descuento de stock. El reintento no duplica.
escritura
mover_pedido
Entregado, cancelado o un paso más en el despacho.
escritura
crear_producto
Agrega un producto al catálogo activo del negocio.
escritura
editar_producto
Cambia solo lo que mandes: nombre, precio, descripción o estado.
escritura
ajustar_inventario
Suma o resta unidades dejando el movimiento registrado.
escritura
crear_cliente
Registra un comprador por su número de WhatsApp.
escritura
agendar_cita
Agenda una visita en la hora local del negocio, sin zona.
escritura
escribirle_al_cliente
WhatsApp por el número del negocio. Su permiso se concede aparte.
escritura
Toda escritura ensaya primero
El agente propone. La persona aprueba.
Con confirmar=false, que es el valor por defecto, la herramienta devuelve lo que haría sin tocar nada. Solo con el sí de una persona se llama otra vez con confirmar=true y la misma clave de idempotencia. Incluye el prompt Brief del día para arrancar cada mañana.
confirmar=falseEnsayo: lo que haría
personaRevisa y aprueba
confirmar=trueSe hace una sola vez
API REST v1
Los 19 endpoints, uno por uno.
Base https://api.zavorai.com/api/v1, llave en Authorization: Bearer y la especificación completa en openapi.json. Elige uno para ver la petición y la respuesta.
GET/api/v1/mesin permiso
Quién soy
De qué negocio es la llave, qué permisos tiene, el plan y los topes. Basta una llave válida: es la primera llamada de cualquier integración o agente.
Con los precios del catálogo, descuenta stock y respeta el tope mensual del plan. Con Idempotency-Key un reintento devuelve la misma respuesta y no duplica.
Exactamente uno de dos: status (delivered, cancelled) o dispatch_stage (alistando, en_camino). El aviso al comprador viene en notify y un fallo de WhatsApp nunca revierte el cambio.
Suma o resta dejando el movimiento registrado. El descuento es atómico: restar de más responde 409 insufficient_stock, y un producto sin inventario, 409 untracked_stock.
Se identifica por su número de WhatsApp. Si ya existe responde 409 already_exists con su id, y uno nuevo queda con marketing_consent: "unknown": el consentimiento lo da él.
Del más reciente al más viejo, paginado por cursor. author dice si habló el comprador, el bot o una persona del equipo: lo que un CRM necesita para llevar la conversación al perfil del cliente.
scheduled_at va en hora local y sin zona: una fecha con Z se rechaza. Si la franja no sirve, el 409 dice por qué: pasado, sin_horario, fuera_de_horario u ocupado.
Por el WhatsApp del negocio, y queda en Conversaciones como si lo hubiera escrito el bot. Su permiso se concede aparte. Fuera de la ventana de 24 horas responde 409 window_closed en vez de fingir que salió.
Petición
curl -X POST https://api.zavorai.com/api/v1/messages \
-H "Authorization: Bearer $ZAVORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"buyer_id": "b81e40c2-…", "text": "Tu pedido va en camino."}'
Respuesta con zvk_test_201
{
"buyer_id": "b81e40c2-…",
"wa_sid": null,
"status": "simulated",
"note": "Llave de prueba: el mensaje NO se envió."
}
Llaves, permisos y pruebas
Arma tu llave y mira lo que puede hacer.
Cada llave lleva solo los permisos que le des, y un permiso de escritura no incluye el de lectura. Prende y apaga permisos: así responde GET /me con esa llave.
Con write:messages la llave habla con la voz del negocio por su propio número. Dásela solo a quien deba escribirle a tus clientes.
Prueba contra la base de verdad, sin guardar nada.
Una llave zvk_test_ recorre el mismo camino que una de producción: las llaves foráneas, las reglas que aíslan tu cuenta y el descuento atómico de stock se evalúan de verdad. Lo único que no ocurre es el guardado. Las llaves de prueba no dependen del plan.
zvk_live_zvk_test_
Lee datos realessísí
Valida permisos, plan, topes y stocksísí
Guarda los cambiossíno
Le manda WhatsApp al compradorsíno, responde simulated
Deja historial del pedidosíno
SDK de Python
Tu negocio en Python, en tres líneas.
El paquete zavora llega pronto a PyPI; mientras tanto está en acceso anticipado: escríbenos por WhatsApp y te lo compartimos. Trae cliente síncrono y asíncrono con la misma superficie, y las herramientas ya declaradas para Claude y OpenAI.
Paginación sola
iter_all() recorre todas las páginas sin que nadie toque el cursor.
Errores con nombre
SinPermiso, NoEncontrado, Conflicto, TopeAlcanzado: nada de comparar textos.
Reintentos que no duplican
Se reintenta lo que no cambió nada. Una escritura sin clave de idempotencia nunca se repite.
Listo para agentes
ZavoraTools: 13 herramientas en formato de Claude o de OpenAI, con ensayo antes de escribir.
$ pip install zavora # pronto en PyPI
from zavora import Zavora
z = Zavora() # lee ZAVORA_API_KEY del entorno
yo = z.me() # qué puede hacer esta llave
print(yo["tenant"]["name"], yo["scopes"])
for pedido in z.orders.iter_all(status="paid"):
print(pedido["id"], pedido["total_amount"])
z.orders.update(pedido_id, dispatch_stage="en_camino")
z.adjust_inventory(producto_id, delta=-3, note="rotura")
from zavora import SinPermiso, Conflicto, TopeAlcanzado
try:
z.send_message(buyer_id, "Tu pedido va en camino")
except SinPermiso:
print("a esta llave le falta el scope write:messages")
except Conflicto as e:
if e.code == "window_closed":
print("pasaron más de 24 h desde su último mensaje")
except TopeAlcanzado as e:
print("ir más despacio:", e.retry_after, "segundos")
from zavora import Zavora
from zavora.agents import ZavoraTools
tools = ZavoraTools(Zavora())
respuesta = claude.messages.create(
model="claude-opus-5",
tools=tools.anthropic(), # o tools.openai()
messages=[{"role": "user", "content": "¿Qué falta despachar?"}],
)
for bloque in respuesta.content:
if bloque.type == "tool_use":
resultado = tools.run(bloque.name, bloque.input)
# una escritura sin confirm=True devuelve {"dry_run": True, ...}
from zavora import AsyncZavora
async with AsyncZavora() as z:
async for pedido in z.orders.iter_all():
if pedido["status"] == "paid":
await z.orders.update(pedido["id"], dispatch_stage="alistando")
Webhooks
Zavora te avisa cuando pasa algo.
Un pedido nuevo, un pago, un cambio de estado, un comprador que llega o un producto que se agota. Cada envío va firmado para que verifiques que salió de Zavora, y se reintenta si tu servidor no responde.
order.paid
Pasa algoorder.paid
POST firmadoX-Zavora-Signature
Tu servidor verificaHMAC-SHA256
Responde 2xxen menos de 10 s
Eventos
order.createdSe creó un pedido (salió del carrito)
order.paidUn pedido quedó pagado
order.status_changedCambió el estado de un pedido
buyer.createdLlegó un comprador nuevo
approval.requestedUna acción espera el sí de una persona
inventory.lowUn producto cruzó su umbral de stock
payment.completedEntró un pago
Si no respondes 2xx, se reintenta
1
2
4
8
16
32
64
128min
Ocho intentos. El id del evento es el mismo en todos: úsalo para no procesar dos veces. Solo https a direcciones públicas, sin seguir redirecciones. El evento de prueba del panel llega sin plan; los eventos reales son del plan Escala.
import hashlib, hmac, time
def verificar(secreto: str, cuerpo: bytes, cabecera: str, tolerancia=300) -> bool:
# X-Zavora-Signature: t=<unix>,v1=<hex>
partes = dict(p.split("=", 1) for p in cabecera.split(","))
t = int(partes["t"])
if abs(time.time() - t) > tolerancia:
return False
esperada = hmac.new(secreto.encode(), f"{t}.".encode() + cuerpo,
hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, partes["v1"])
import crypto from "node:crypto";
// cuerpo: el Buffer crudo, antes de parsear el JSON
export function verificar(secreto, cuerpo, cabecera, tolerancia = 300) {
const partes = Object.fromEntries(cabecera.split(",").map((p) => p.split("=")));
const t = Number(partes.t);
if (Math.abs(Date.now() / 1000 - t) > tolerancia) return false;
const esperada = crypto.createHmac("sha256", secreto)
.update(`${t}.`).update(cuerpo).digest("hex");
const a = Buffer.from(esperada), b = Buffer.from(partes.v1 ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Las reglas que conviene conocer antes de la primera línea.
Zavora se opera por programa de tres formas —la API REST, el SDK de Python y el servidor MCP— 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. Arriba está la vista rápida; aquí van las reglas que conviene conocer antes de escribir la primera línea.
Si llegaste 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).
Convenciones de la API
La base es https://api.zavorai.com/api/v1 y la especificación OpenAPI 3 vive en /api/v1/openapi.json. Autenticas con Authorization: Bearer zvk_live_… (o con la cabecera X-Api-Key) y la llave decide de qué negocio es cada petición. El primer llamado recomendado es GET /me: dice de qué negocio es la llave, qué permisos tiene, el plan y los topes, así sabes qué puedes hacer antes de chocar con un error.
Los errores siempre tienen la misma forma: {"error": {"code": "not_found", "message": "…"}}.
Las listas van paginadas por cursor: {"data": [...], "next_cursor": "…"}, con limit entre 1 y 100 (25 por defecto).
Los montos viajan como texto decimal ("12500.00") para que ningún centavo se pierda en un float, y las fechas son ISO-8601 en UTC.
products y buyers aceptan ?updated_since=: un ERP pregunta «¿qué cambió desde ayer?» en vez de traer el catálogo entero.
El tope es de 120 peticiones por minuto por llave, y cada respuesta trae RateLimit-Remaining para que veas tu cupo sin descubrirlo chocando. Un id de otra cuenta responde 404, igual que uno que no existe: la API no confirma que exista.
Reintentar sin duplicar
Todos los POST de escritura aceptan la cabecera Idempotency-Key. Si la red se cae y repites la llamada con la misma clave, recibes la misma respuesta (con Idempotent-Replayed: true) sin descontar stock dos veces ni mandar dos WhatsApp. El SDK la manda solo en cada create(), y por eso esas escrituras sí se reintentan seguras; una escritura sin clave nunca se repite, porque si el servidor alcanzó a aplicarla repetirla crearía un segundo pedido.
Mover un pedido
PATCH /orders/{id} recibe exactamente uno de dos campos. status es la verdad del dinero: pasa a delivered o cancelled, y cancelar devuelve el stock y desactiva el link de pago. dispatch_stage es la capa operativa encima: alistando o en_camino, solo en pedidos pagados, y nunca retrocede.
La respuesta trae el pedido y el resultado del aviso al comprador: enviado, ventana_cerrada, fallo o no_aplica. Un fallo de WhatsApp nunca revierte el cambio; el pedido ya se movió y el panel ofrece reintentar el aviso. Los pedidos que entran por el chat —por texto, foto o nota de voz— son los mismos que mueves por la API.
Catálogo, inventario y compradores
Un producto creado por la API aterriza en el catálogo activo y respeta el tope de productos del plan: una llave no es una puerta trasera al plan. stock: null significa que el producto no lleva inventario, que no es lo mismo que 0 (agotado).
POST /inventory/adjust suma o resta dejando el movimiento en el libro con su razón. El descuento es atómico: dos ajustes al mismo tiempo no dejan el inventario en negativo, y restar de más responde 409 insufficient_stock.
Un comprador se identifica por su número de WhatsApp; si ya existe, la API responde 409 already_exists con su id. Uno creado por API queda con marketing_consent: "unknown": crearlo no es permiso para mandarle campañas, ese consentimiento lo da él.
Mensajes y la ventana de 24 horas
POST /messages manda un texto por el WhatsApp del negocio y lo deja en Conversaciones, igual que si lo hubiera escrito el bot. Por eso el permiso write:messages se concede aparte y nunca viene con los demás: esa llave habla con la voz del negocio por su propio número.
La ventana de 24 horas es de Meta, no de Zavora. Fuera de ella el texto libre no se entrega, así que la API responde 409 window_closed en vez de fingir que salió. Antes de automatizar mensajes vale la pena leer qué permite la WhatsApp Business API y qué cuesta cada mensaje.
Citas en la hora del negocio
GET /availability?date=AAAA-MM-DD devuelve las franjas libres en la hora local del negocio, y su zona viene en GET /me. Para agendar, scheduled_at va en hora local y sin zona (2026-09-20T09:00): una fecha en UTC se rechaza, porque agendaría a otra hora sin avisar. Si la franja no sirve, el 409 dice por qué: pasado, sin_horario, fuera_de_horario u ocupado.
Aprobaciones de una persona
Un negocio puede exigir que una persona apruebe ciertas acciones antes de que ocurran: un pedido desde cierto monto, un ajuste grande de inventario, una baja de precio fuerte. Viene apagado. Cuando una regla se activa, la acción no se hace y la respuesta es 200 con "status": "pending_approval", no un error: un 4xx haría que reintentaras y crearías una segunda aprobación para lo mismo. El evento approval.requested avisa por webhook.
Es la misma idea de las herramientas para agentes, que ensayan antes de escribir. La diferencia entre esto y un chatbot de reglas está en agente de IA vs chatbot: un agente decide qué herramienta usar, y por eso conviene que una persona apruebe lo que cambia el negocio.
Trazas: qué hizo tu agente
El negocio ve en el panel qué acciones hizo cada llave, cómo salieron y cuánto tardaron. Se registran las escrituras y los fallos, no las lecturas que salen bien. Tres cabeceras opcionales hacen esa consola legible, y el SDK y el MCP las mandan solos: X-Run-Id agrupa varias llamadas como una sesión de agente, X-Agent-Id le pone nombre a tu agente y X-Zavora-Source dice si vino de api, mcp, bot o panel. El cuerpo de la petición no se guarda: un mensaje o una dirección quedan como <N caracteres>.
Una cuenta de Zavora y una llave creada en el panel, en Integraciones → API y webhooks. Las llaves de prueba no dependen del plan: también en los 14 días gratis puedes crear una y probar la API, el SDK y el MCP. Las llaves de producción y los webhooks de eventos reales son del plan Escala. La llave se muestra una sola vez: Zavora guarda solo su hash.
¿Puedo probar sin afectar mi negocio?
Sí. Una llave de prueba (zvk_test_) valida todo contra la base real —permisos, plan, topes, stock, aislamiento entre cuentas— y no confirma ni un cambio. Tampoco envía WhatsApp: responde que fue simulado.
¿Un agente de IA puede crear pedidos solo?
Puede, pero por defecto no lo hace de una. Las herramientas de escritura ensayan primero: devuelven lo que harían sin tocar nada, para que una persona lo apruebe antes de confirmarlo.
¿Qué clientes de IA funcionan con el servidor MCP?
Hoy, Claude Code, Claude Desktop y Cursor: lo corren en tu computador como MCP local (stdio). La versión alojada, para ChatGPT y otros clientes web, llega próximamente. Mientras tanto, en acceso anticipado, el modo HTTP se puede correr en un servidor propio con HTTPS: registras la URL que termina en /mcp y mandas la llave en la cabecera Authorization. En ese modo el servidor no guarda llaves; cada petición trae la suya.
¿Hay SDK para otros lenguajes?
Por ahora solo Python. Desde cualquier otro lenguaje la API se usa directo: la especificación OpenAPI 3 está en /api/v1/openapi.json y sirve para generar un cliente o para declarar las herramientas de un agente.
¿Qué pasa si se me pierde la llave?
Se revoca desde el panel y deja de funcionar al instante. Puedes tener varias llaves con permisos distintos, y el panel muestra el último uso de cada una para saber cuál está viva.