← Volver a tutoriales
21.09.2026 4 min de lectura

Gemini para crear una demo de pedidos con Gemini API desde cero

Aprende a montar una demo de pedidos con Gemini API, convertir respuestas en JSON, validarlas y conectarlas con Google Sheets para probar el flujo sin inventar funciones.

Este tutorial usa Google Gemini para resolver una tarea concreta: recibir un pedido de un negocio tradicional y devolver un JSON validado. Es útil para validar el flujo antes de pagar por integraciones o construir un MVP completo. No reemplaza un sistema de inventario, facturación ni cobro.

Antes de empezar, revisa la documentación oficial de API keys y structured output. Si tu proyecto usa Cloud Functions, consulta Google Cloud Functions documentation.

1. Prepara el proyecto

  1. Crea una cuenta de Google Cloud y un proyecto para tu prueba.
  2. Activa la Generative Language API en el proyecto.
  3. Crea una API key desde la consola de Google Cloud. No la compartas ni la subas a GitHub.
  4. Instala Node.js, abre una terminal y ejecuta npm init -y y npm i @google/genai dotenv.
  5. Crea un archivo .env con GEMINI_API_KEY=tu_clave. Agrega .env a tu .gitignore.

2. Define un prompt limitado

El prompt debe explicar qué información falta y qué formato debe entregar Gemini. No le pidas que invente stock, precios ni disponibilidad.

SYSTEM_PROMPT = `
Eres un asistente para registrar pedidos. Devuelve únicamente JSON válido.
Campos requeridos: cliente, email, direccion, items, observaciones.
items: [{producto, cantidad, precioUnitario}].
cantidad: número entero mayor que cero.
precioUnitario: número con máximo dos decimales. Si falta, usa null.
Si falta un campo, usa "" o null. No inventes stock ni disponibilidad.`;

USER_PROMPT = `Registra este pedido:
${pedidoTexto}`;`;

El prompt anterior usa parámetros disponibles en la documentación de structured output. Ajusta los nombres de campos si tu modelo o SDK cambia.

3. Pide JSON y valida la respuesta

La respuesta se guarda como text y se convierte con JSON.parse. Después se valida que los campos obligatorios existan y que las cantidades sean enteras positivas.

import 'dotenv/config';
import { GoogleGenAI, Schema } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const itemsSchema = new Schema({
  type: 'array',
  items: {
    type: 'object',
    properties: {
      producto: { type: 'string' },
      cantidad: { type: 'integer' },
      precioUnitario: { type: ['number', 'null'] }
    },
    required: ['producto', 'cantidad', 'precioUnitario']
  }
});

const pedido = {
  cliente: 'María González',
  email: 'maria@example.com',
  direccion: 'Calle 5 N° 123',
  items: [{ producto: 'Martillo 400g', cantidad: 2, precioUnitario: 12500 }],
  observaciones: 'Entregar antes de las 18:00'
};

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [{ role: 'user', parts: [{ text: USER_PROMPT }] }],
  config: {
    responseSchema: new Schema({
      type: 'object',
      properties: {
        cliente: { type: 'string' },
        email: { type: 'string' },
        direccion: { type: 'string' },
        items: itemsSchema,
        observaciones: { type: 'string' }
      },
      required: ['cliente', 'email', 'direccion', 'items']
    }),
    temperature: 0
  }
});

const data = JSON.parse(response.text);
if (!data.items.length) throw new Error('No hay productos');
for (const item of data.items) {
  if (!Number.isInteger(item.cantidad) || item.cantidad <= 0) throw new Error('Cantidad inválida');
}
console.log(JSON.stringify(data, null, 2));`;

Antes de usar esta prueba, revisa en Gemini model availability si el modelo solicitado está disponible en tu región y cuenta.

Ejemplo concreto: ferretería de barrio

Un dueño escribe: «María necesita dos martillos de 400 gramos, entrega a las 18:00». El sistema devuelve un JSON con dos filas de pedido. La ferretería puede copiarlo a Google Sheets o enviarlo por correo. Si el dueño confirma el stock y el precio, recién ahí se registra la venta. Para una prueba sin servidor, abre Gemini API Playground y prueba el prompt con una clave temporal.

Errores frecuentes

  • Usar una clave en código público o compartida por correo.
  • Confundir una respuesta de Gemini con una venta confirmada; falta validación y revisión humana.
  • Pedir inventario, precios o disponibilidad sin conectar una base de datos real.
  • Guardar todo el prompt y la respuesta sin revisar qué datos personales se están procesando.

Cuándo conviene y cuál es el siguiente paso

Conviene cuando quieres probar cómo un negocio interpreta pedidos, detectar campos faltantes y medir el tiempo de atención. No conviene para cobros, facturación legal o inventario sin una fuente oficial. El siguiente paso es guardar pedidos aprobados en una base de datos y registrar cada intento para corregir errores.

Fuentes para profundizar