API v1 · SDK de Python · Servidor MCP

Zavora para desarrolladores y agentes de IA

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.

pip install zavora pronto en PyPI

Actualizado el · Por Brayan Pedraza · 5 min de lectura

$ curl https://api.zavorai.com/api/v1/me \
    -H "Authorization: Bearer zvk_test_a1b2c3d4…"
{
  "tenant": { "name": "Tienda Don Carlos", "currency": "COP" },
  "scopes": ["read:orders", "read:products"],
  "mode": "test",
  "sandbox": true,
  "limits": { "requests_per_minute": 120 }
}

● 200 OKRateLimit-Remaining: 119zvk_test_ · nada se guarda

  • 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.

Servidor MCP

Tu negocio, dentro de Claude o Cursor.

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. 1
    Crea una llave de prueba

    Panel → Integraciones → API y webhooks. Elige Prueba y los permisos que quieras darle a la IA.

  2. 2
    Conecta tu cliente

    Una línea en la terminal o un bloque de JSON, según dónde trabajes.

  3. 3
    Pregúntale

    «¿Cómo vamos hoy?», «¿qué pedidos faltan por despachar?», «crea el pedido de Don Carlos».

claude mcp add zavora \
  -e ZAVORA_API_KEY=zvk_test_… \
  -- uvx --from /ruta/a/zavora-mcp zavora-mcp

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.

  1. confirmar=falseEnsayo: lo que haría
  2. personaRevisa y aprueba
  3. 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.

Petición
curl https://api.zavorai.com/api/v1/me \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "tenant": { "name": "Tienda Don Carlos", "country": "CO", "currency": "COP",
              "timezone": "America/Bogota", "language": "es" },
  "api_key": { "name": "Agente de ventas", "prefix": "zvk_live_a1b2c3d4" },
  "scopes": ["read:orders", "read:products"],
  "plan": { "key": "pro", "status": "active", "writes_allowed": true },
  "limits": { "requests_per_minute": 120, "page_size_max": 100 },
  "mode": "live",
  "sandbox": false,
  "api_version": "1.0.0"
}
GET/api/v1/ordersread:orders

Listar pedidos

Más recientes primero, paginados por cursor. Sin status deja por fuera los carritos (draft).

Petición
curl "https://api.zavorai.com/api/v1/orders?status=paid&limit=25" \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "data": [
    {
      "id": "7f3c2a91-…",
      "status": "paid",
      "source": "bot",
      "total_amount": "219000.00",
      "currency": "COP",
      "paid_at": "2026-10-01T14:02:11Z",
      "items": [
        { "name": "Arroz Diana 5 kg", "quantity": 10.0,
          "unit_price": "21900.00", "line_total": "219000.00" }
      ]
    }
  ],
  "next_cursor": "eyJjIjoiMjAyNi0x…"
}
GET/api/v1/orders/{id}read:orders

Leer un pedido

Un pedido con sus líneas, total, método de entrega y fecha de pago. Un id de otra cuenta responde 404, igual que uno que no existe.

Petición
curl https://api.zavorai.com/api/v1/orders/7f3c2a91-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "id": "7f3c2a91-…",
  "status": "paid",
  "buyer_id": "b81e40c2-…",
  "total_amount": "219000.00",
  "currency": "COP",
  "delivery_method": "delivery",
  "delivery_address": "Cra 7 # 45-12, Bogotá",
  "paid_at": "2026-10-01T14:02:11Z",
  "items": [ … ]
}
POST/api/v1/orderswrite:orders

Crear un pedido

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.

Petición
curl -X POST https://api.zavorai.com/api/v1/orders \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Idempotency-Key: pedido-don-carlos-0412" \
  -H "Content-Type: application/json" \
  -d '{"buyer_id": "b81e40c2-…",
       "items": [{"product_id": "a4d2…", "quantity": 10}]}'
Respuesta 201
{
  "id": "9c1d55e0-…",
  "status": "confirmed",
  "source": "api",
  "total_amount": "219000.00",
  "currency": "COP",
  "items": [ … ]
}
PATCH/api/v1/orders/{id}write:orders

Mover un pedido

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.

Petición
curl -X PATCH https://api.zavorai.com/api/v1/orders/7f3c2a91-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dispatch_stage": "en_camino"}'
Respuesta 200
{
  "order": { "id": "7f3c2a91-…", "status": "paid", … },
  "notify": { "result": "enviado", "error": null, "event_id": "…" }
}
GET/api/v1/productsread:products

Listar productos

El catálogo con precio, stock y SKU. updated_since trae solo lo que cambió y active filtra por estado.

Petición
curl "https://api.zavorai.com/api/v1/products?updated_since=2026-09-30T00:00:00Z" \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "data": [
    {
      "id": "a4d2e7f1-…",
      "name": "Arroz Diana 5 kg",
      "sku": "ARR-5K",
      "unit": "bulto",
      "price": "21900.00",
      "currency": "COP",
      "stock": 46,
      "is_active": true,
      "updated_at": "2026-09-30T18:20:04Z"
    }
  ],
  "next_cursor": null
}
GET/api/v1/products/{id}read:products

Leer un producto

stock: null significa que el producto no lleva inventario, que no es lo mismo que 0 (agotado). La API respeta la diferencia.

Petición
curl https://api.zavorai.com/api/v1/products/a4d2e7f1-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "id": "a4d2e7f1-…",
  "name": "Arroz Diana 5 kg",
  "price": "21900.00",
  "currency": "COP",
  "stock": 46,
  "is_active": true
}
POST/api/v1/productswrite:products

Crear un producto

Aterriza en el catálogo activo y respeta el tope de productos del plan: una llave de API no es una puerta trasera al plan.

Petición
curl -X POST https://api.zavorai.com/api/v1/products \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Panela 500 g", "price": 3500, "stock": 120, "unit": "und"}'
Respuesta 201
{
  "id": "e02b9a4c-…",
  "name": "Panela 500 g",
  "price": "3500.00",
  "currency": "COP",
  "stock": 120,
  "is_active": true
}
PATCH/api/v1/products/{id}write:products

Editar un producto

Solo toca los campos que mandes. Para mover stock usa /inventory/adjust: así el movimiento queda en el libro con su razón.

Petición
curl -X PATCH https://api.zavorai.com/api/v1/products/e02b9a4c-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price": 4000}'
Respuesta 200
{
  "id": "e02b9a4c-…",
  "name": "Panela 500 g",
  "price": "4000.00",
  "updated_at": "2026-10-01T15:41:09Z"
}
POST/api/v1/inventory/adjustwrite:inventory

Ajustar el stock

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.

Petición
curl -X POST https://api.zavorai.com/api/v1/inventory/adjust \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "a4d2e7f1-…", "delta": -3, "note": "rotura en bodega"}'
Respuesta 200
{
  "product_id": "a4d2e7f1-…",
  "stock": 43,
  "delta": -3
}
GET/api/v1/buyersread:buyers

Listar compradores

Con su número de WhatsApp, etapa y consentimiento de marketing. También acepta updated_since.

Petición
curl "https://api.zavorai.com/api/v1/buyers?limit=50" \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "data": [
    {
      "id": "b81e40c2-…",
      "name": "Tienda Don Carlos",
      "whatsapp_number": "+573001112233",
      "email": null,
      "stage": "nuevo",
      "marketing_consent": "granted"
    }
  ],
  "next_cursor": null
}
GET/api/v1/buyers/{id}read:buyers

Leer un comprador

Un comprador por su id, con las mismas reglas de aislamiento: otra cuenta no puede confirmar que exista.

Petición
curl https://api.zavorai.com/api/v1/buyers/b81e40c2-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "id": "b81e40c2-…",
  "name": "Tienda Don Carlos",
  "whatsapp_number": "+573001112233",
  "stage": "nuevo",
  "marketing_consent": "granted"
}
POST/api/v1/buyerswrite:buyers

Crear un comprador

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.

Petición
curl -X POST https://api.zavorai.com/api/v1/buyers \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_number": "+573004445566", "name": "Ana Rojas"}'
Respuesta 201
{
  "id": "d7a1f3b9-…",
  "name": "Ana Rojas",
  "whatsapp_number": "+573004445566",
  "stage": "nuevo",
  "marketing_consent": "unknown"
}
PATCH/api/v1/buyers/{id}write:buyers

Editar un comprador

Nombre, correo y notas. El número no se cambia: es la identidad del comprador y su historial cuelga de él.

Petición
curl -X PATCH https://api.zavorai.com/api/v1/buyers/d7a1f3b9-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@correo.com", "notes": "Prefiere entregas en la mañana"}'
Respuesta 200
{
  "id": "d7a1f3b9-…",
  "name": "Ana Rojas",
  "email": "ana@correo.com",
  "updated_at": "2026-10-01T16:05:33Z"
}
GET/api/v1/buyers/{id}/messagesread:messages

Historial de conversación

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.

Petición
curl https://api.zavorai.com/api/v1/buyers/b81e40c2-…/messages \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "data": [
    { "direction": "outbound", "author": "bot",
      "text": "Listo, tu pedido va en camino.", "created_at": "2026-10-01T15:12:40Z" },
    { "direction": "inbound", "author": "buyer",
      "text": "¿Ya salió lo de hoy?", "created_at": "2026-10-01T15:12:02Z" }
  ],
  "next_cursor": "eyJjIjoiMjAyNi0x…"
}
GET/api/v1/availabilityread:appointments

Disponibilidad de un día

Las franjas en la hora local del negocio (su zona viene en GET /me). Las que ya pasaron no se listan, porque no se pueden ofrecer.

Petición
curl "https://api.zavorai.com/api/v1/availability?date=2026-10-02" \
  -H "Authorization: Bearer $ZAVORA_API_KEY"
Respuesta 200
{
  "date": "2026-10-02",
  "available": true,
  "slots": [
    { "time": "09:00", "free": true },
    { "time": "10:00", "free": false },
    { "time": "11:00", "free": true }
  ]
}
POST/api/v1/appointmentswrite:appointments

Agendar una cita

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.

Petición
curl -X POST https://api.zavorai.com/api/v1/appointments \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"buyer_id": "b81e40c2-…", "scheduled_at": "2026-10-02T09:00", "duration_minutes": 60}'
Respuesta 201
{
  "id": "3e8f0c21-…",
  "buyer_id": "b81e40c2-…",
  "scheduled_at": "2026-10-02T14:00:00Z",
  "duration_minutes": 60,
  "status": "agendada",
  "source": "api"
}
PATCH/api/v1/appointments/{id}write:appointments

Cerrar o cancelar una cita

Solo estados finales: cumplida, no_asistio o cancelada. Reprogramar no es un estado: se cancela y se agenda otra.

Petición
curl -X PATCH https://api.zavorai.com/api/v1/appointments/3e8f0c21-… \
  -H "Authorization: Bearer $ZAVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "cumplida"}'
Respuesta 200
{
  "id": "3e8f0c21-…",
  "status": "cumplida",
  "scheduled_at": "2026-10-02T14:00:00Z"
}
POST/api/v1/messageswrite:messages

Escribirle a un comprador

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.

Modo de la llave
Permisos

Pedidos

Catálogo e inventario

Compradores

Citas

Aparte de todo lo demás

zvk_test_a1b2c3d4•••••••••••• Prueba
Endpoints que abre5 de 19
Herramientas MCP6 de 17
GET /api/v1/me200
{
  "tenant": { "name": "Tienda Don Carlos", "currency": "COP" },
  "api_key": { "prefix": "zvk_test_a1b2c3d4" },
  "scopes": [
    "read:orders",
    "read:products"
  ],
  "mode": "test",
  "sandbox": true,
  "limits": { "requests_per_minute": 120 }
}

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")

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.

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. 1
  2. 2
  3. 4
  4. 8
  5. 16
  6. 32
  7. 64
  8. 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"])

La guía, en detalle

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.

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>.

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 y cómo lo usa una distribuidora.

Preguntas frecuentes

Lo que preguntan antes de empezar

¿Qué necesito para empezar?

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.

La llave de prueba no guarda nada. Empieza por ahí.

Valida permisos, stock y reglas contra la base de verdad, sin confirmar un solo cambio.