{"openapi":"3.1.0","info":{"title":"Zavora API pública","description":"API pública v1: productos, pedidos y compradores del tenant de la llave.\n\nConvenciones (todas las rutas):\n- Auth: ``Authorization: Bearer zvk_live_…`` (o ``X-Api-Key``).\n- Errores: ``{\"error\": {\"code\": \"...\", \"message\": \"...\"}}``.\n- Listas: ``{\"data\": [...], \"next_cursor\": \"...\" | null}``; se pide la siguiente\n  página con ``?cursor=``. Orden: más recientes primero. ``limit`` 1–100.\n- Montos como cadena decimal (\"12500.00\"): un float pierde centavos.\n- Fechas ISO-8601 en UTC con ``Z``.\n\n🔴 Aislamiento: cada consulta filtra por ``ctx.tenant_id`` Y la sesión tiene la\nRLS fijada al tenant de la llave (`auth.py`). Un id de otro tenant es 404, igual\nque un id que no existe: no se confirma que exista.\n\n\n## Empieza por `GET /me`\nDice 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 403.\n\n## SDK\n`pip install zavora` — cliente síncrono y asíncrono, errores tipados, paginación automática y las herramientas listas para un agente.","version":"1.0.0"},"paths":{"/api/v1/me":{"get":{"tags":["api-publica-v1"],"summary":"Quién soy","description":"Tenant de la llave, permisos concedidos, plan y topes. Es el primer llamado que debería hacer un integrador o un agente: dice qué puede hacer ANTES de intentarlo y fallar con un 403. No exige ningún scope — solo una llave válida.","operationId":"quien_soy_api_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`validation_error` — el cuerpo no cumple. El mensaje dice qué campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/products":{"get":{"tags":["api-publica-v1"],"summary":"Listar productos","operationId":"listar_productos_api_v1_products_get","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true (defecto) solo activos; omitir el filtro con false/null no aplica","default":true,"title":"Active"},"description":"true (defecto) solo activos; omitir el filtro con false/null no aplica"},{"name":"updated_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601: solo lo cambiado desde entonces (sync incremental).","title":"Updated Since"},"description":"ISO-8601: solo lo cambiado desde entonces (sync incremental)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["api-publica-v1"],"summary":"Crear un producto","description":"Aterriza en el catálogo activo del negocio. `stock: null` (el defecto) significa SIN seguimiento de inventario, que no es lo mismo que `0` (agotado). Respeta el tope de productos del plan.","operationId":"crear_producto_api_v1_products_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductoIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/products/{product_id}":{"get":{"tags":["api-publica-v1"],"summary":"Leer un producto","operationId":"leer_producto_api_v1_products__product_id__get","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","title":"Product Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["api-publica-v1"],"summary":"Editar un producto","description":"Solo se toca lo que venga en el cuerpo. Para cambiar el stock hay que usar `POST /inventory/adjust`: aquí se fija un valor absoluto y allá queda el movimiento con su razón.","operationId":"editar_producto_api_v1_products__product_id__patch","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","title":"Product Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductoPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buyers/{buyer_id}/messages":{"get":{"tags":["api-publica-v1"],"summary":"Historial de conversación","description":"Los mensajes de WhatsApp con un comprador, del más reciente al más viejo, paginados por cursor. Es lo que un CRM necesita para llevar la conversación —no solo el contacto— al perfil del cliente.","operationId":"listar_mensajes_api_v1_buyers__buyer_id__messages_get","parameters":[{"name":"buyer_id","in":"path","required":true,"schema":{"type":"string","title":"Buyer Id"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inventory/adjust":{"post":{"tags":["api-publica-v1"],"summary":"Ajustar el stock","description":"Suma o resta unidades dejando el movimiento en el libro de inventario con razón `adjustment`, para que el negocio pueda responder «¿dónde quedó mi stock?».\n\nUn producto sin seguimiento (`stock: null`) no se puede ajustar: primero hay que ponerle un stock con `PATCH /products/{id}`. Restar más de lo que hay se rechaza — el inventario no va a negativo.","operationId":"ajustar_inventario_api_v1_inventory_adjust_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AjusteIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buyers":{"post":{"tags":["api-publica-v1"],"summary":"Crear un comprador","description":"El número de WhatsApp identifica al comprador dentro del negocio; si ya existe se responde 409 con su id para que lo edites.\n\n🔴 El comprador queda con `marketing_consent: \"unknown\"`. Crearlo por API **no es** un permiso para mandarle campañas: el consentimiento lo da él, no el integrador.","operationId":"crear_comprador_api_v1_buyers_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompradorNuevo"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["api-publica-v1"],"summary":"Listar compradores","operationId":"listar_compradores_api_v1_buyers_get","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"updated_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601: solo lo cambiado desde entonces (sync incremental).","title":"Updated Since"},"description":"ISO-8601: solo lo cambiado desde entonces (sync incremental)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buyers/{buyer_id}":{"patch":{"tags":["api-publica-v1"],"summary":"Editar un comprador","description":"Nombre, correo y notas. El número de WhatsApp no se cambia: es la identidad del comprador y su historial cuelga de él.","operationId":"editar_comprador_api_v1_buyers__buyer_id__patch","parameters":[{"name":"buyer_id","in":"path","required":true,"schema":{"type":"string","title":"Buyer Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompradorPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["api-publica-v1"],"summary":"Leer un comprador","operationId":"leer_comprador_api_v1_buyers__buyer_id__get","parameters":[{"name":"buyer_id","in":"path","required":true,"schema":{"type":"string","title":"Buyer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/leads":{"post":{"tags":["api-publica-v1"],"summary":"Enviar un lead","description":"Misma normalización que la Entrada de leads: alias en español e inglés (`name`/`nombre`, `phone`/`telefono`/`celular`/`whatsapp`, `email`/`correo`, `company`/`empresa`, `title`/`cargo`, `city`/`ciudad`, `message`/`mensaje`, `source`/`fuente`, `utm_*`, `external_id`, `consent`, `test`). Necesita teléfono (se normaliza a E.164 con el país del negocio) o correo; sin teléfono el lead queda `rechazado` (422): Zavora identifica a cada contacto por su WhatsApp.\n\nCrea o completa el comprador (no pisa nombre ni correo que ya tenga) y emite `lead.received`. `test: true` no crea contacto.\n\nIdempotente por `Idempotency-Key` o `external_id`: un reenvío responde `duplicado: true` con el mismo `lead_id`.\n\n🔴 Zavora **nunca** le escribe al lead por su cuenta.","operationId":"enviar_lead_api_v1_leads_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":190},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Cuerpo"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["api-publica-v1"],"summary":"Listar leads recibidos","description":"Los leads que llegaron por la Entrada de leads o por `POST /leads`, del más reciente al más viejo, paginados por cursor. Se guardan 90 días.\n\n🔴 **PII:** con solo `leads:read`, `telefono` y `email` salen enmascarados (`+573•••••4567`, `a•••@dominio.co`) y `mensaje` sale `null`. Si la llave TAMBIÉN tiene `read:buyers` —el permiso que ya expone el WhatsApp y el correo del contacto— salen completos. La respuesta lo dice en `pii`: `masked` | `full`.","operationId":"listar_leads_api_v1_leads_get","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(creado|actualizado|rechazado|prueba)$"},{"type":"null"}],"title":"Estado"}},{"name":"origen","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(entrada_leads|api_v1|formulario|meta_lead_ads|tiendanube)$"},{"type":"null"}],"title":"Origen"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/messages":{"post":{"tags":["api-publica-v1"],"summary":"Escribirle a un comprador","description":"Manda un mensaje de texto por el WhatsApp del negocio y lo deja en Conversaciones, igual que si lo hubiera escrito el bot.\n\n🔴 Habla con la voz del negocio por su propio número: el scope `write:messages` se concede aparte y nunca viene con los demás.\n\n**La ventana de 24 h es de Meta, no nuestra**: fuera de ella el texto libre no se entrega, y la API responde `409 window_closed` en vez de fingir que salió. Se reabre cuando el comprador vuelve a escribir.","operationId":"enviar_mensaje_api_v1_messages_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MensajeIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/availability":{"get":{"tags":["api-publica-v1"],"summary":"Disponibilidad de un día","description":"Franjas de un día con su estado, en la **hora local del negocio** (`timezone` viene en `GET /me`). Las franjas ya pasadas no se listan: no son ofrecibles.\n\n`{\"date\": \"2026-09-20\", \"slots\": [{\"time\": \"09:00\", \"free\": true}]}`, o `available: false` con el motivo si ese día no hay agenda.","operationId":"disponibilidad_api_v1_availability_get","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","description":"AAAA-MM-DD, hora local del negocio","title":"Date"},"description":"AAAA-MM-DD, hora local del negocio"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/appointments":{"post":{"tags":["api-publica-v1"],"summary":"Agendar una cita","description":"`scheduled_at` va en la **hora local del negocio** y sin zona (`2026-09-20T09:00`): mandarla en UTC agendaría a otra hora sin avisar, así que una fecha con `Z` se rechaza.\n\nValida contra el horario real y las citas ya agendadas; si la franja no sirve responde `409` diciendo por qué.","operationId":"agendar_cita_api_v1_appointments_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitaIn"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/appointments/{appointment_id}":{"patch":{"tags":["api-publica-v1"],"summary":"Cerrar o cancelar una cita","description":"Estados terminales: `cumplida`, `no_asistio`, `cancelada`. Reprogramar no es un estado — se cancela y se agenda otra.","operationId":"cerrar_cita_api_v1_appointments__appointment_id__patch","parameters":[{"name":"appointment_id","in":"path","required":true,"schema":{"type":"string","title":"Appointment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Cuerpo"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders":{"get":{"tags":["api-publica-v1"],"summary":"Listar pedidos","description":"Por defecto excluye los carritos (`draft`); pídelos con `status=draft`.","operationId":"listar_pedidos_api_v1_orders_get","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["draft","awaiting_distributor","awaiting_fulfillment","awaiting_address","pending","confirmed","paid","delivered","cancelled"],"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["api-publica-v1"],"summary":"Crear un pedido","description":"Crea un pedido CONFIRMADO con precios del catálogo (nunca del cliente), descuenta stock y respeta el tope mensual del plan. Mismo camino que el bot: `_apply_items_to_draft`, `_recompute_total` y `commit_order_stock`. Envía `Idempotency-Key` para reintentar sin duplicar.","operationId":"crear_pedido_api_v1_orders_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PedidoIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{order_id}":{"get":{"tags":["api-publica-v1"],"summary":"Leer un pedido","operationId":"leer_pedido_api_v1_orders__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["api-publica-v1"],"summary":"Mover un pedido","description":"Marca el pedido como entregado o cancelado (`status`), o avanza su etapa de despacho (`dispatch_stage`). Exactamente uno de los dos por llamada.\n\n`status` es la verdad del dinero; `dispatch_stage` es la capa operativa encima y solo avanza mientras el pedido está pagado. Cancelar devuelve el stock y mata el link de pago.\n\nEl comprador recibe un WhatsApp cuando corresponde: `notify.result` dice si salió (`enviado`), si su ventana de 24 h estaba cerrada (`ventana_cerrada`) o si falló (`fallo`). Un fallo de WhatsApp NO revierte el cambio.\n\nSi el negocio configuró una aprobación para esta acción, la respuesta trae `status: pending_approval` y el pedido NO se mueve.","operationId":"actualizar_pedido_api_v1_orders__order_id__patch","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActualizarPedido"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integraciones":{"get":{"tags":["api-publica-v1"],"summary":"Catálogo de integraciones y estado de las conexiones","description":"El catálogo universal de Zavora (lo mismo que ve el panel en Integraciones) con el estado de cada conexión de ESTE negocio. Filtros: `q` (texto libre, con sinónimos), `categoria`, `estado` (`conectada`, `disponible`, `beta`, `planificada`…), `solo_conectadas`. `conexion` es `null` si no está conectada; si lo está trae `estado`, `cuenta`, `ultimo_ok_en` y `ultimo_error`. Nunca trae credenciales ni configuración.","operationId":"listar_integraciones_api_v1_integraciones_get","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Q"}},{"name":"categoria","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Categoria"}},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Estado"}},{"name":"solo_conectadas","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Solo Conectadas"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/oportunidades":{"get":{"tags":["api-publica-v1"],"summary":"Buscar licitaciones públicas","description":"Procesos de contratación pública ABIERTOS de una fuente (`fuente`): hoy `secop_ii` (Colombia) y las demás fuentes de sector público que Zavora tenga conectables (la lista vigente sale en el 422 si mandas una que no existe).\n\nSin `q`, usa las palabras clave (y el monto mínimo) que el negocio guardó al conectar la fuente en el panel; si no la conectó, `q` es obligatorio. `region` es el departamento (SECOP II) o la UF (PNCP). Paginado por cursor; `limit` ≤ 50.\n\nSon datos abiertos: no usa credenciales del negocio. Tope propio: 60 búsquedas cada 10 minutos por negocio (la fuente es un servicio público compartido).","operationId":"buscar_oportunidades_api_v1_oportunidades_get","parameters":[{"name":"fuente","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":40,"pattern":"^[a-z0-9_]+$","title":"Fuente"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Q"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Region"}},{"name":"monto_minimo","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000000000000000,"minimum":0},{"type":"null"}],"title":"Monto Minimo"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/automatizaciones/corridas":{"get":{"tags":["api-publica-v1"],"summary":"Corridas de automatizaciones","description":"Las ejecuciones de las automatizaciones del negocio (por agenda y por evento), de la más reciente a la más vieja. Filtros: `estado_cola` (`pendiente`, `reintentando`, `muerta` = cola de fallidos, `hecha`, `esperando_aprobacion`), `resultado` (`ok`, `error`, `sin_destinatarios`, `omitida`) y `automatizacion_id`. Solo lectura: el reintento manual sigue siendo de un admin en el panel. `detalle` es una lista blanca (evento, correlation_id, approval_id, duracion_ms, condiciones_cumplen).","operationId":"listar_corridas_api_v1_automatizaciones_corridas_get","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"estado_cola","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(pendiente|reintentando|muerta|hecha|esperando_aprobacion)$"},{"type":"null"}],"title":"Estado Cola"}},{"name":"resultado","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(ok|error|sin_destinatarios|omitida)$"},{"type":"null"}],"title":"Resultado"}},{"name":"automatizacion_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}],"title":"Automatizacion Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integraciones/salud":{"get":{"tags":["api-publica-v1"],"summary":"Salud de las integraciones del negocio","description":"Lo mismo que el panel muestra en Integraciones → Salud, MEDIDO de las tablas (nada estimado): estado de cada conexión (`ultimo_ok_en`, `ultimo_error`, `requiere_reautorizacion`), colas de trabajos (pendientes, reintentando, fallidos en 24 h), corridas de automatizaciones de las últimas 24 h (ok, error, muertas, esperando aprobación), eventos frenados por límites y leads recibidos/rechazados en 24 h. Nunca trae credenciales ni configuración.","operationId":"salud_integraciones_api_v1_integraciones_salud_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`validation_error` — el cuerpo no cumple. El mensaje dice qué campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integraciones/solicitudes":{"post":{"tags":["api-publica-v1"],"summary":"Solicitar una integración","description":"Registra que este negocio quiere una integración (la misma acción que «Solicitar integración» del panel): con `slug` para una del catálogo o con `nombre` para una herramienta que no está. Idempotente por (negocio, integración): repetirla no crea otra fila, solo actualiza la nota; `ya_solicitada` dice si ya existía. NO conecta nada, no pide credenciales y no le escribe a nadie: es demanda para el equipo de Zavora. Tope: 30 por hora por negocio. Con una llave de prueba no se guarda.","operationId":"solicitar_integracion_api_v1_integraciones_solicitudes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolicitudIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"get":{"tags":["api-publica-v1"],"summary":"Listar webhooks suscritos","description":"Los endpoints de webhook del negocio (los creados en el panel y los creados por API). Nunca devuelve el secreto de firma. Pide `webhooks:read`.","operationId":"listar_webhooks_api_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`validation_error` — el cuerpo no cumple. El mensaje dice qué campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["api-publica-v1"],"summary":"Suscribir un webhook (REST Hook)","description":"Crea un endpoint que recibirá los eventos elegidos, firmados con `X-Zavora-Signature` (HMAC-SHA256 `t=<unix>,v1=<hex>` sobre `\"<t>.<cuerpo>\"`). **El `secret` se devuelve solo en esta respuesta.** Mismas reglas que el panel: solo `https://`, nada de redes internas ni IPs reservadas, sin usuario:clave en la URL, tope de endpoints por cuenta (`webhook_limit_reached`, 409) y la misma URL no se registra dos veces (`already_exists`, 409). Pide `webhooks:write`. Pensado para Zapier/Make/n8n: suscribir al activar, `DELETE` al apagar.","operationId":"crear_webhook_api_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookNuevo"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{webhook_id}":{"delete":{"tags":["api-publica-v1"],"summary":"Desuscribir un webhook","description":"Borra el endpoint (y su historial de entregas). Un id de otro negocio o que no existe responde 404. Pide `webhooks:write`.","operationId":"borrar_webhook_api_v1_webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key` — la llave falta, está mal escrita o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope` (a la llave le falta un permiso) o `plan_feature_required` (el plan no incluye `api_access`). El segundo no se arregla cambiando de llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`. Un id de OTRO negocio también responde 404: la API no confirma que exista algo que no es tuyo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — 120 peticiones por minuto por llave. Trae `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ActualizarPedido":{"properties":{"status":{"anyOf":[{"type":"string","enum":["delivered","cancelled"]},{"type":"null"}],"title":"Status"},"dispatch_stage":{"anyOf":[{"type":"string","enum":["alistando","en_camino"]},{"type":"null"}],"title":"Dispatch Stage"}},"type":"object","title":"ActualizarPedido"},"AjusteIn":{"properties":{"product_id":{"type":"string","maxLength":36,"title":"Product Id"},"delta":{"type":"integer","title":"Delta"},"note":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Note"}},"type":"object","required":["product_id","delta"],"title":"AjusteIn"},"CitaIn":{"properties":{"buyer_id":{"type":"string","maxLength":36,"title":"Buyer Id"},"scheduled_at":{"type":"string","maxLength":32,"title":"Scheduled At"},"duration_minutes":{"type":"integer","maximum":480.0,"minimum":15.0,"title":"Duration Minutes","default":60},"product_id":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}],"title":"Product Id"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes"}},"type":"object","required":["buyer_id","scheduled_at"],"title":"CitaIn"},"CompradorIn":{"properties":{"whatsapp_number":{"type":"string","maxLength":20,"minLength":6,"title":"Whatsapp Number"},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name"}},"type":"object","required":["whatsapp_number"],"title":"CompradorIn"},"CompradorNuevo":{"properties":{"whatsapp_number":{"type":"string","maxLength":20,"minLength":7,"title":"Whatsapp Number"},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Email"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes"}},"type":"object","required":["whatsapp_number"],"title":"CompradorNuevo"},"CompradorPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Email"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes"}},"type":"object","title":"CompradorPatch"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ItemIn":{"properties":{"product_id":{"type":"string","format":"uuid","title":"Product Id"},"quantity":{"type":"integer","maximum":100000.0,"minimum":1.0,"title":"Quantity"}},"type":"object","required":["product_id","quantity"],"title":"ItemIn"},"MensajeIn":{"properties":{"buyer_id":{"type":"string","maxLength":36,"title":"Buyer Id"},"text":{"type":"string","maxLength":4000,"minLength":1,"title":"Text"}},"type":"object","required":["buyer_id","text"],"title":"MensajeIn"},"PedidoIn":{"properties":{"buyer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Buyer Id"},"buyer":{"anyOf":[{"$ref":"#/components/schemas/CompradorIn"},{"type":"null"}]},"items":{"items":{"$ref":"#/components/schemas/ItemIn"},"type":"array","maxItems":100,"minItems":1,"title":"Items"},"delivery_method":{"anyOf":[{"type":"string","enum":["pickup","delivery"]},{"type":"null"}],"title":"Delivery Method"},"delivery_address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Delivery Address"}},"type":"object","required":["items"],"title":"PedidoIn"},"ProductoIn":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"sku":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Sku"},"unit":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Unit"},"pack_size":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Pack Size"},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Description"},"price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Price"},"stock":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Stock"},"is_active":{"type":"boolean","title":"Is Active","default":true}},"type":"object","required":["name"],"title":"ProductoIn"},"ProductoPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name"},"sku":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Sku"},"unit":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Unit"},"pack_size":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Pack Size"},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Description"},"price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Price"},"stock":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Stock"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"ProductoPatch","description":"Todo opcional: solo se toca lo que viene. `None` explícito no se distingue\nde ausente en JSON, así que para borrar un precio se manda `price: 0`."},"SolicitudIn":{"properties":{"slug":{"anyOf":[{"type":"string","maxLength":40,"minLength":2,"pattern":"^[a-z0-9_]+$"},{"type":"null"}],"title":"Slug","description":"Id de una integración del catálogo (`GET /integraciones`)."},"nombre":{"anyOf":[{"type":"string","maxLength":80,"minLength":2},{"type":"null"}],"title":"Nombre","description":"Herramienta que NO está en el catálogo (texto libre)."},"nota":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Nota","description":"Para qué la necesitas (opcional)."}},"type":"object","title":"SolicitudIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookNuevo":{"properties":{"url":{"type":"string","maxLength":500,"minLength":10,"title":"Url","description":"URL https pública que recibirá los eventos (p. ej. la de un Zap)."},"eventos":{"items":{"type":"string"},"type":"array","maxItems":8,"minItems":1,"title":"Eventos","description":"Eventos a recibir (`lead.received`, `order.paid`, …). También se acepta `events`."},"descripcion":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Descripcion","description":"Texto libre para reconocerlo en el panel (p. ej. «Zapier: Zap 123»)."}},"type":"object","required":["url","eventos"],"title":"WebhookNuevo"},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_scope"},"message":{"type":"string","example":"La llave no tiene el permiso write:orders."}},"required":["code","message"]}},"required":["error"]}},"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"zvk_live_…","description":"Llave del negocio. Se crea en el panel, en Integraciones → API y webhooks."}}},"security":[{"ApiKey":[]}],"servers":[{"url":"https://api.zavorai.com","description":"Producción"}],"webhooks":{"order.created":{"post":{"summary":"Se creó un pedido (salió del carrito)","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["order.created"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"order.paid":{"post":{"summary":"Un pedido quedó pagado","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["order.paid"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"order.status_changed":{"post":{"summary":"Cambió el estado de un pedido","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["order.status_changed"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"buyer.created":{"post":{"summary":"Llegó un comprador nuevo","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["buyer.created"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"approval.requested":{"post":{"summary":"Una acción quedó esperando el sí de una persona","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["approval.requested"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"inventory.low":{"post":{"summary":"Un producto bajó de su umbral de stock","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["inventory.low"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"payment.completed":{"post":{"summary":"Entró un pago","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["payment.completed"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}},"lead.received":{"post":{"summary":"Llegó un lead (Entrada de leads o API v1)","description":"Firmado. La firma y los reintentos se explican en `docs/integraciones/API-PUBLICA-V1.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lead.received"]},"api_version":{"type":"string","example":"v1"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Recibido. Cualquier 2xx sirve; otra cosa se reintenta."}}}}}}