Tu IA lee lo que pasa con tus vinos

Qué hay

• GET /cuenta — quién eres: bodega, plan, alcances de la clave y las vistas que puedes pedir.
• GET /cuenta/vinos — tus vinos y añadas, con el estado de la firma (firmada = firma Ed25519 activa, la misma que enseña el registro público), los idiomas publicados y la dirección oficial de cada añada firmada. Vista privada: incluye lo no firmado.
• GET /cuenta/analitica/{vista}?mes=YYYY-MM — la analítica mensual. Vistas: resumen · vinos · cta · geo-idioma · contexto · lecturas-api.
• GET /cuenta/recados?desde=YYYY-MM-DD&estado=nuevo|gestionado — pedidos, peticiones de visita, recados y llamadas a devolver que el sommelier anotó en tu nombre.
• PATCH /cuenta/recados/{id} — marcar un recado como gestionado (o reabrirlo). Solo el estado; nada más se escribe.
• GET /cuenta/reservas?desde=YYYY-MM-DD — el diario de reservas que gestionó el sommelier y por qué puerta entraron.
• POST /cuenta/borradores — dejar la ficha de una añada preparada: tú propones, el bodeguero revisa y firma. Rellena solo los huecos.

Cómo autenticar

La clave la crea el bodeguero en su panel (Bústia → Recados → «Claves de acceso para tu IA»). Empieza por slk_, se enseña una sola vez y se puede revocar en cualquier momento. Va en la cabecera Authorization:

curl -H "Authorization: Bearer slk_TU_CLAVE" https://app.sommelierlab.com/api/public/v1/cuenta

Cada clave lleva alcances; la ruta pide uno concreto y si la clave no lo lleva responde 403.

• 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

Ejemplos

# Tus vinos y añadas
curl -H "Authorization: Bearer slk_TU_CLAVE" https://app.sommelierlab.com/api/public/v1/cuenta/vinos

# El resumen del mes pasado
curl -H "Authorization: Bearer slk_TU_CLAVE" "https://app.sommelierlab.com/api/public/v1/cuenta/analitica/resumen?mes=2026-08"

# Recados nuevos desde el 1 de septiembre
curl -H "Authorization: Bearer slk_TU_CLAVE" "https://app.sommelierlab.com/api/public/v1/cuenta/recados?desde=2026-09-01&estado=nuevo"

# Marcar el recado 42 como gestionado
curl -X PATCH -H "Authorization: Bearer slk_TU_CLAVE" -H "Content-Type: application/json" \
     -d '{"estado":"gestionado"}' https://app.sommelierlab.com/api/public/v1/cuenta/recados/42

Respuesta típica de /cuenta/vinos:

{
  "ok": true,
  "bodega_id": "B001",
  "total": 1,
  "vinos": [{
    "vino_id": "V001", "nombre": "Nombre del vino", "tipo": "Tinto", "do": "DO Costers del Segre", "activo": true,
    "anyadas": [{
      "anyada": "2024", "estado": "publicada", "firmada": true, "firmada_en": "2026-06-01T10:00:00.000Z", "verificada_en": "2026-06-01T10:00:00.000Z",
      "publicada_en": "2026-06-02T09:00:00.000Z", "idiomas": ["ca", "en", "es"],
      "idv_url": "https://idv.sommelierlab.com/V001-2024"
    }]
  }]
}

Dejar un borrador de ficha

Lo único que se puede escribir. La regla, en una frase: tú propones, el bodeguero firma. Se rellenan los huecos de esa añada (se crea si no existe) y no se pisa nunca nada: lo que la bodega ya había escrito vuelve en conflictos para que lo mire ella.

curl -X POST -H "Authorization: Bearer slk_TU_CLAVE" -H "Content-Type: application/json" \
     -d '{"vino_id":"V002","anyada":"2025","campos":{"graduacion":"14,5","lote":"L-2025","numero_botellas":"12000"}}' \
     https://app.sommelierlab.com/api/public/v1/cuenta/borradores

{
  "ok": true, "borrador_id": 17, "vino_id": "V002", "anyada": "2025", "anyada_creada": false,
  "aplicado":   [{ "campo": "graduacion", "etiqueta": "Graduación alcohólica", "valor": 14.5 }],
  "conflictos": [{ "campo": "lote", "etiqueta": "Lote", "actual": "L-24", "propuesto": "L-2025" }],
  "enlace_revision": "https://app.sommelierlab.com/studio?bodega=B001&vino=V002&anada=2025",
  "resumen": "Tu IA dejó 1 campo en V002 2025 · 1 no se tocó porque ya tenía valor · revisar y firmar"
}

• Lo firmado no se toca. Si un campo está dentro de una firma vigente (la legal o la de identidad), la petición entera es 409 y no se escribe nada. Cambiar eso es cosa de la bodega, que después vuelve a firmar.
• Ingredientes, alérgenos y nutrición: 422. Son listas cerradas y entran por el lector legal del panel, con la etiqueta o el análisis delante.
• El nombre, el relato, el logo y los colores: 422. Son la voz de la casa; en la v1 no se tocan desde fuera.
• Un vino que no existe: 404. Dar de alta un vino nuevo se hace desde el panel.
• La añada se crea si hace falta. Si esa cosecha todavía no existe y algo va a entrar en ella, se crea vacía y sin firma (anyada_creada). Si todo lo que propones ya tenía valor, no se crea nada.
• Nada se publica ni se firma. El bodeguero lo ve en su buzón, pestaña «De tu IA» (y en su correo, si lo tiene puesto), y decide en su editor.
• Campos que se pueden proponer: 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

La ficha técnica

Además de campos, la propuesta puede traer ficha_tecnica: las casillas del análisis, el coupage, la crianza, la vendimia, el viñedo, el envase, las certificaciones, el clima y el servicio, por su id y en plano. Qué casillas hay, de qué tipo, en qué unidad y con qué rango te lo dice GET /cuenta/borradores (con ?bloque=analisis para uno solo). Mismas reglas: huecos sí, pisar no, lo firmado es 409; la forma la juzga la misma validación que el editor de la bodega (un pH de 40 o un coupage que pasa del 100 % son 422, con el motivo).

curl -X POST -H "Authorization: Bearer slk_TU_CLAVE" -H "Content-Type: application/json" \
     -d '{"vino_id":"V002","anyada":"2025","ficha_tecnica":{
          "analisis.ph":3.45,
          "analisis.acidez_total":{"valor":72.5,"metodo":"OIV-MA-AS313-01"},
          "coupage.variedades":[{"variedad":"Garnacha Tinta","porcentaje":60},{"variedad":"Cariñena","porcentaje":40}],
          "coupage.mencion_etiqueta":"varias"}}' \
     https://app.sommelierlab.com/api/public/v1/cuenta/borradores

Límites y reglas

• Las vistas de analítica son mensuales. Se piden por mes=YYYY-MM (sin el parámetro, el mes en curso). No hay datos en tiempo real.
• 60 llamadas por minuto por clave. Si te pasas: 429 con Retry-After.
• Solo tu bodega. La bodega la fija la clave, nunca la petición. No hay parámetro para pedir otra.
• Solo agregados y lo que el cliente te deja a ti (recado, reserva). Nunca la identidad ni el rastro individual de quien escanea: ni IP, ni identificadores de sesión, ni el número desde el que llamó.
• Escribir, solo borradores. Lo demás es lectura (más el estado de un recado). Nunca se firma, nunca se publica y nunca se pisa lo que la bodega ya escribió.
• Plan. Esta API va con el plan Premium. Con otro plan la clave se crea igual pero las peticiones responden 402 con el motivo.
• Códigos: 401 sin clave, mal formada o revocada · 402 plan sin API · 403 alcance que la clave no lleva · 404 recado o vino que no es tuyo · 409 campo firmado · 422 campo que no se puede proponer · 429 demasiadas llamadas.
• CORS abierto: se puede llamar desde un navegador, pero la clave es secreta; no la pongas en una web pública.

Conecta tu Claude

Además de la API de arriba, la misma clave abre un servidor MCP en https://app.sommelierlab.com/api/mcp: tu asistente se conecta con una línea y pregunta en tu idioma, sin leerse nada.

• mis_vinos — tus vinos y añadas, con firma e idiomas
• analitica — la analítica del mes (las mismas vistas)
• recados — los recados que tomó el sommelier
• reservas — el diario de reservas
• idv_de — la identidad pública (IDV) de una añada tuya
• casillas_ficha_tecnica — qué casillas tiene la ficha técnica, con su tipo y su unidad (con el alcance de borradores)
• proponer_borrador — dejar un borrador de ficha, ficha técnica incluida (con el alcance de borradores)

Todas son de lectura salvo proponer_borrador, que solo aparece si la clave lleva el alcance de borradores: rellena huecos y nunca firma ni publica.

En Claude Code, una vez:

claude mcp add --transport http sommelierlab https://app.sommelierlab.com/api/mcp \
  --header "Authorization: Bearer slk_TU_CLAVE"

En Claude Desktop, en Ajustes → Desarrollador → Editar configuración (el archivo claude_desktop_config.json); necesita Node instalado:

{
  "mcpServers": {
    "sommelierlab": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.sommelierlab.com/api/mcp", "--header", "Authorization:${SLAB_CLAVE}"],
      "env": { "SLAB_CLAVE": "Bearer slk_TU_CLAVE" }
    }
  }
}

Y ya puedes preguntar: «¿qué vino se escaneó más en agosto?», «¿tengo recados sin gestionar?», «¿qué dice la ficha pública de mi 2024?».

Si tu programa no habla MCP

Dale esta página (o el openapi.json) y tu clave: con eso cualquier asistente o script llama a las rutas de arriba y te contesta igual. Y con el alcance de borradores marcado puedes pedirle también «deja preparada la ficha de la añada 2025 con estos datos del análisis»: la prepara y el bodeguero la firma.