{"openapi":"3.1.0","info":{"title":"SommelierLab · el enchufe · API de tu cuenta","version":"1.0.0","summary":"Lo que pasa con tus vinos, para tu propia IA o tu programa de gestión. Solo tu bodega; escribir, solo borradores.","description":"Con una clave `slk_…` creada por el bodeguero en su panel, su IA lee lo mismo que él ve: vinos y añadas, analítica MENSUAL (no hay tiempo real), recados y reservas. La bodega la fija la clave; no hay parámetro para pedir otra. Nunca se sirven datos individuales de quien escanea (ni IP, ni identificadores de sesión, ni número de teléfono del que llama). Lo único que se puede escribir son BORRADORES de ficha (POST /cuenta/borradores): nunca se firma, nunca se publica y nunca se pisa lo que la bodega ya escribió. Documentación legible: https://app.sommelierlab.com/partners/enchufe","contact":{"email":"hola@sommelierlab.com"}},"servers":[{"url":"https://app.sommelierlab.com/api/public/v1"}],"security":[{"clave":[]}],"x-limites":{"llamadas_por_minuto":60,"analitica":"mensual, parámetro mes=YYYY-MM"},"x-alcances":{"leer:idv":"Tus vinos y añadas, con el estado de la firma y los idiomas publicados","leer:analitica":"La analítica mensual de tus vinos (la misma que ves en el panel)","leer:recados":"Los recados y las reservas que el sommelier toma en tu nombre","escribir:borradores":"Dejar la ficha de una añada preparada, ficha técnica incluida (análisis, coupage…), para que tú la revises y la firmes. Nunca pisa lo que ya escribiste, y nunca firma ni publica"},"paths":{"/cuenta":{"get":{"operationId":"cuenta","summary":"Quién eres: bodega, plan, alcances de la clave y vistas disponibles.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cuenta"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuenta/vinos":{"get":{"operationId":"vinos","summary":"Tus vinos y añadas con estado de firma, idiomas publicados y dirección oficial (IDV).","description":"Alcance `leer:idv`. Vista privada: incluye añadas sin firmar (la API pública /wines solo sirve las firmadas).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vinos"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuenta/analitica/{vista}":{"get":{"operationId":"analitica","summary":"Analítica mensual de tus vinos, la misma que el panel.","description":"Alcance `leer:analitica`. Las vistas son MENSUALES: `mes=YYYY-MM` (por defecto, el mes en curso).","parameters":[{"name":"vista","in":"path","required":true,"schema":{"type":"string","enum":["resumen","vinos","cta","geo-idioma","contexto","lecturas-api"]}},{"name":"mes","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"description":"Mes, YYYY-MM. Sin él, el mes en curso."}],"responses":{"200":{"description":"OK. La forma depende de la vista; siempre lleva `tenant_id` (tu bodega), `mes` y `vista`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"`mes` con formato distinto de YYYY-MM.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Vista desconocida. La respuesta lista las válidas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuenta/recados":{"get":{"operationId":"recados","summary":"Pedidos, peticiones de visita, recados y llamadas a devolver que el sommelier anotó en tu nombre.","description":"Alcance `leer:recados`. Sin identificadores de la conversación ni del número que llamó.","parameters":[{"name":"desde","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Solo desde esta fecha (YYYY-MM-DD)."},{"name":"estado","in":"query","required":false,"schema":{"type":"string","enum":["nuevo","gestionado"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recados"}}}},"400":{"description":"`desde` o `estado` inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuenta/recados/{id}":{"patch":{"operationId":"marcarRecado","summary":"Cambiar el estado de un recado tuyo (gestionado ↔ nuevo). Nada más se escribe.","description":"Alcance `leer:recados`. Un recado de otra bodega, aunque se sepa el id, es 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["estado"],"properties":{"estado":{"type":"string","enum":["nuevo","gestionado"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"recado":{"$ref":"#/components/schemas/Recado"}}}}}},"400":{"description":"Cuerpo sin `estado` válido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No es tuyo o no existe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuenta/borradores":{"get":{"operationId":"casillasFichaTecnica","summary":"Las casillas de la ficha técnica que se pueden proponer en `ficha_tecnica`.","description":"Alcance `escribir:borradores`. Sale del registro de la ficha técnica: por bloque (análisis, coupage, crianza, vendimia, viñedo, envase, certificaciones, clima, servicio), cada casilla con su id, nombre, ayuda, nivel (vino o añada), si entra en la firma, tipo, unidad, decimales, rango, opciones, precisión de las fechas y, en listas y grupos, sus partes.","parameters":[{"name":"bloque","in":"query","required":false,"schema":{"type":"string"},"description":"Solo este bloque (analisis, coupage…)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"version_registro":{"type":"integer"},"como_se_propone":{"type":"array","items":{"type":"string"}},"bloques":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No hay ese bloque.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"dejarBorrador","summary":"Dejar la ficha de una añada preparada para que el bodeguero la revise y la firme.","description":"Alcance `escribir:borradores`. Rellena SOLO los huecos: lo que la bodega ya había escrito no se pisa —vuelve en `conflictos`— y lo que está dentro de una firma vigente (QR1 o IDV) es 409, sin excepción. Si la añada no existe todavía, se crea vacía y sin firma. Aquí no se publica, no se firma y no se cobra nada: el bodeguero lo ve en su buzón (pestaña «De tu IA») y decide en su editor. Ingredientes, alérgenos y nutrición no se escriben a mano (422): van por el lector legal del panel. El nombre, el relato, el logo y los colores son la voz de la casa y en la v1 no se tocan (422). `ficha_tecnica` (opcional) lleva casillas de la ficha técnica por su id, con las mismas reglas; su forma la juzga la validación del editor (tipo, rango, partes obligatorias, suma del coupage…) y un fallo es 422 con `errores` casilla a casilla.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropuestaBorrador"}}}},"responses":{"200":{"description":"Aceptado (aunque no haya entrado ningún campo: mira `aplicado` y `conflictos`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Borrador"}}}},"400":{"description":"Falta `vino_id`, `anyada` (cuatro cifras) o algo que proponer (`campos` o `ficha_tecnica`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Ese vino no es de tu bodega o no existe. Dar de alta un vino se hace desde el panel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Algún campo está bajo una firma vigente: `campos` dice cuáles. No se ha tocado nada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Campo que no se puede proponer: lista legal, editorial, de la bodega, inexistente, o valor con mala forma.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuenta/reservas":{"get":{"operationId":"reservas","summary":"Diario de reservas que gestionó el sommelier (crear, cancelar, sin hueco) y por qué puerta entraron.","description":"Alcance `leer:recados`.","parameters":[{"name":"desde","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reservas"}}}},"400":{"description":"`desde` inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sin clave, mal formada o revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan de la bodega no incluye la API (va con Premium). `message` lo explica.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"La clave no lleva el alcance que pide esta ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Más de 60 llamadas por minuto con esta clave. Cabecera Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"clave":{"type":"http","scheme":"bearer","bearerFormat":"slk_ + 32 caracteres","description":"La crea el bodeguero en su panel; se enseña una vez; se puede revocar."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"},"message":{"type":"string"}}},"Cuenta":{"type":"object","properties":{"ok":{"type":"boolean"},"bodega":{"type":"object","properties":{"bodega_id":{"type":"string"},"nombre":{"type":["string","null"]}}},"plan":{"type":"object","properties":{"tier":{"type":"string"},"nombre":{"type":"string"}}},"clave":{"type":"object","properties":{"nombre":{"type":"string"},"prefijo":{"type":"string"},"alcances":{"type":"array","items":{"type":"object","properties":{"alcance":{"type":"string"},"que_permite":{"type":"string"}}}}}},"vistas":{"type":"object","additionalProperties":true},"limites":{"type":"object","properties":{"llamadas_por_minuto":{"type":"integer"},"nota":{"type":"string"}}},"documentacion":{"type":"string"}}},"Anyada":{"type":"object","properties":{"anyada":{"type":"string"},"estado":{"type":["string","null"]},"firmada":{"type":"boolean"},"firmada_en":{"type":["string","null"],"format":"date-time","description":"Firma Ed25519 activa (la del registro público)."},"verificada_en":{"type":["string","null"],"format":"date-time","description":"Verificación antigua del panel; informativa, no es la firma."},"publicada_en":{"type":["string","null"],"format":"date-time"},"idiomas":{"type":"array","items":{"type":"string"}},"idv_url":{"type":["string","null"]}}},"Vino":{"type":"object","properties":{"vino_id":{"type":"string"},"nombre":{"type":["string","null"]},"tipo":{"type":["string","null"]},"do":{"type":["string","null"]},"activo":{"type":"boolean"},"anyadas":{"type":"array","items":{"$ref":"#/components/schemas/Anyada"}}}},"Vinos":{"type":"object","properties":{"ok":{"type":"boolean"},"bodega_id":{"type":"string"},"total":{"type":"integer"},"vinos":{"type":"array","items":{"$ref":"#/components/schemas/Vino"}}}},"Recado":{"type":"object","properties":{"id":{"type":"integer"},"tipo":{"type":"string","description":"pedido · reserva · recado · callback"},"canal":{"type":["string","null"],"description":"telefono · whatsapp · mostrador · botella_chat · avatar · web"},"nombre":{"type":["string","null"]},"empresa":{"type":["string","null"]},"telefono":{"type":["string","null"]},"email":{"type":["string","null"]},"detalle":{"type":["string","null"]},"items":{"type":["array","null"],"items":{"type":"object","additionalProperties":true}},"fecha_visita":{"type":["string","null"]},"personas":{"type":["integer","null"]},"urgencia":{"type":["string","null"]},"estado":{"type":"string","enum":["nuevo","gestionado"]},"creado_en":{"type":"string","format":"date-time"}}},"Recados":{"type":"object","properties":{"ok":{"type":"boolean"},"bodega_id":{"type":"string"},"total":{"type":"integer"},"recados":{"type":"array","items":{"$ref":"#/components/schemas/Recado"}}}},"Reserva":{"type":"object","properties":{"id":{"type":"integer"},"accion":{"type":"string","description":"crear · cancelar · sin_hueco"},"canal":{"type":["string","null"]},"nombre":{"type":["string","null"]},"inicio":{"type":["string","null"],"format":"date-time"},"personas":{"type":["integer","null"]},"proveedor":{"type":["string","null"]},"booking_id":{"type":["string","null"]},"creado_en":{"type":"string","format":"date-time"}}},"Reservas":{"type":"object","properties":{"ok":{"type":"boolean"},"bodega_id":{"type":"string"},"total":{"type":"integer"},"reservas":{"type":"array","items":{"$ref":"#/components/schemas/Reserva"}}}},"PropuestaBorrador":{"type":"object","required":["vino_id","anyada"],"properties":{"vino_id":{"type":"string","description":"El código del vino, como V002. Lo devuelve /cuenta/vinos."},"anyada":{"type":"string","pattern":"^\\d{4}$","description":"El año, cuatro cifras. Si esa añada no existe, se crea."},"campos":{"type":"object","additionalProperties":true,"description":"Lo que propones, por clave. Las que se aceptan: graduacion, volumen, denominacion, embotellador, tipo, variedad, do, ean, elaboracion, vinificacion, crianza, region, parcela, altitud, suelo, temperatura, vendimia, referencia, libreta, lote, fecha_embotellado, fecha_cosecha, numero_botellas, procedencia, conservacion, operador, enologo."},"ficha_tecnica":{"type":"object","additionalProperties":true,"description":"Casillas de la ficha técnica, plano, id → valor (\"analisis.ph\": 3.45). La lista con tipos y unidades: GET /cuenta/borradores. Hace falta `campos`, `ficha_tecnica` o los dos."}}},"Borrador":{"type":"object","properties":{"ok":{"type":"boolean"},"borrador_id":{"type":["integer","null"]},"vino_id":{"type":"string"},"anyada":{"type":"string"},"anyada_creada":{"type":"boolean","description":"true = esa añada no existía y se ha creado, sin firma."},"aplicado":{"type":"array","items":{"type":"object","properties":{"campo":{"type":"string"},"etiqueta":{"type":"string"},"valor":{}}}},"conflictos":{"type":"array","description":"Lo que NO se ha tocado porque ya tenía valor.","items":{"type":"object","properties":{"campo":{"type":"string"},"etiqueta":{"type":"string"},"actual":{},"propuesto":{}}}},"rechazados":{"type":"array","description":"Lo que la capa de permisos no dejó escribir (raro).","items":{"type":"object","properties":{"campo":{"type":"string"},"motivo":{"type":"string"}}}},"avisos":{"type":"array","description":"Ficha técnica: reglas que avisan sin bloquear (lo propuesto entró).","items":{"type":"object","properties":{"campo":{"type":"string"},"motivo":{"type":"string"}}}},"enlace_revision":{"type":"string","description":"Dónde lo revisa y lo firma el bodeguero."},"resumen":{"type":"string"}}}}}}