¿Qué es JSON? Guía básica para dueños de pequeños negocios

Hola, soy yeonghyeon, lidero el desarrollo en 3Min API.

En la anterior publicación sobre API dije que "una API es una ventanilla que envía y recibe mensajes con una forma acordada en una dirección acordada". En aquel momento dejé a propósito para después la historia de "qué forma tienen esos mensajes" — y hoy es esa pieza que faltaba. Esta publicación trata de la forma real de los "mensajes" que viajan entre el contenedor (base de datos) y la ventanilla (API): JSON.

El objetivo de la publicación de hoy no es "memorizar sintaxis". Basta con llegar a la sensación de "puedo escribir un evento de mi negocio como un único bloque de JSON". Una vez que tengas esa sensación, hablar con desarrolladores y con la IA se vuelve un paso más cercano — compartís el mismo idioma. No hacen falta conocimientos previos.

Qué es JSON

Empecemos por la definición del diccionario. Wikipedia describe JSON (JavaScript Object Notation) como "un formato de archivo estándar abierto que utiliza texto legible por humanos para almacenar y transmitir objetos de datos que consisten en pares atributo-valor y arrays".

En una línea:

JSON = texto escrito en un formato acordado para que los sistemas puedan intercambiar datos sin que un humano pierda la capacidad de leerlo con sus propios ojos.

En realidad, para intercambiar mensajes entre sistemas hay varias opciones: JSON, XML, YAML, Protocol Buffers y más. Entonces ¿por qué las API web de hoy eligen JSON de forma tan abrumadora? La razón es sencilla: tanto las personas como los programas lo entienden de un vistazo. Un desarrollador puede abrirlo en un bloc de notas y leerlo; un servidor puede analizarlo rápido. No hay muchos formatos que hagan bien las dos cosas a la vez.

Por qué hace falta una "forma acordada"

En las dos publicaciones anteriores ya tenemos las herramientas contenedor (DB) y ventanilla (API). Pero tener herramientas no hace que los datos fluyan solos. Si cada persona que se acercara a la ventanilla entregara un papel distinto con cualquier escritura, el empleado no podría procesar ni una sola solicitud.

Por eso los bancos preparan formularios estándar por adelantado: resguardos de depósito, de retiro, solicitudes de transferencia. Con formularios iguales, el empleado puede validar rápido y el registro queda automático. Una API hace lo mismo por el mismo motivo: fija de antemano la promesa "los mensajes que entren por esta ventanilla deben tener esta forma". La sintaxis estándar para escribir esa "forma" es JSON.

Antes de que JSON se asentara, cada sistema inventaba su propio formato de mensajes. Unos usaban texto de una línea separado por comas, otros envolvían todo en etiquetas XML, otros creaban un formato binario propio que solo se documentaba en papeles internos. Cada nuevo socio comercial significaba revisar documentos y escribir de nuevo el código de análisis. Ahora que JSON es el estándar de facto, una sola frase — "intercambiemos en JSON" — basta para arrancar la mayoría de colaboraciones.

Entender JSON a través de Excel

Antes de ver la sintaxis de JSON directamente, partamos de una herramienta que ya conoces: la hoja de cálculo. Imagina una hoja de Excel. La fila superior contiene los nombres de las columnas (producto, cantidad, importe…), y cada fila debajo representa una transacción.

Trasladar esa estructura a JSON encaja de forma muy natural:

• El nombre de columna en Excel → la clave (key) en JSON
• El valor de una celda → el valor (value) en JSON
• Una fila en Excel → un objeto ({}) en JSON
• Varias filas en Excel → un array ([]) en JSON

Supongamos que una fila de la hoja de pedidos tiene esta pinta:

order_id	product	quantity	amount
A-2026-0001	Château Margaux 2020	2	480000

Si movemos esta fila tal cual a un objeto JSON, queda así:

{
  "order_id": "A-2026-0001",
  "product": "Château Margaux 2020",
  "quantity": 2,
  "amount": 480000
}

Dos puntos junto a cada nombre, una coma entre los elementos, un par de llaves envolviéndolo todo. Esas son todas las reglas. Este bloque es un objeto JSON que contiene exactamente la misma información que una fila de Excel.

Entonces, si ya tenemos Excel, ¿por qué hace falta JSON aparte? Las diferencias son dos: jerarquía y flexibilidad. Excel difícilmente admite meter una tabla dentro de una sola celda, y en cuanto las filas empiezan a tener columnas distintas la gestión se derrumba. JSON, en cambio, permite con toda naturalidad colocar otro objeto o array en la posición del valor, y los campos opcionales que varían entre pedidos caben sin esfuerzo. Si una hoja de Excel es un "libro de cuentas plano", JSON se parece más a un "libro de cuentas que se pliega como una carpeta cuando hace falta".

El albarán del dueño de la tienda de vino

Continuemos la escena de la publicación anterior. Llega un pedido nuevo desde la tienda online. El POS de la tienda física y los restaurantes asociados miran la misma base de datos, y la ventanilla que los conecta es la API. Echemos un vistazo al mensaje que realmente cruza esa ventanilla.

La tienda online envía a la API de "crear pedido" de la tienda de vino un bloque de JSON como este:

{
  "order_id": "A-2026-0412",
  "customer": {
    "id": "C-00871",
    "name": "Alex",
    "email": "alex@example.com"
  },
  "items": [
    {
      "sku": "WINE-MARGAUX-2020",
      "name": "Château Margaux 2020",
      "quantity": 2,
      "unit_price": 240000
    },
    {
      "sku": "WINE-OPUS-2019",
      "name": "Opus One 2019",
      "quantity": 1,
      "unit_price": 520000
    }
  ],
  "total_amount": 1000000,
  "ordered_at": "2026-04-15T14:23:00+09:00"
}

Dentro de este único bloque ya están quién (customer), qué (items), cuánto (total_amount) y cuándo (ordered_at) compró. Aquí se ve de un vistazo qué significaba lo del "libro que se pliega en lugar de uno plano". El cliente es un bloque con sus propios subcampos (nombre, correo), y los artículos comprados son una lista con dos entradas. En Excel esa información habría tenido que vivir en hojas separadas de clientes, pedidos y detalle de pedidos; aquí queda ordenadamente dentro de un mismo sobre.

En cuanto la ventanilla de la API recibe este sobre, comprueba si se ajusta a la "forma acordada". Si order_id está vacío, si quantity trae algo que no es un número, o si falta email dentro de customer, lo rechaza ahí mismo. Gracias a eso, la base de datos acumula pedidos siempre con la misma forma, lo que evita tropezones más adelante al sacar estadísticas o exportarlos a otro sistema.

Cuando el pago se completa, la pasarela de pago envía otro JSON a una ventanilla distinta de la tienda diciendo "este pedido se pagó correctamente". Como ya comenté la vez anterior, a esa forma en la que el otro sistema te avisa primero se le llama webhook. El cuerpo del webhook también es JSON. Petición: JSON. Respuesta: JSON. Notificación: JSON. Casi todos los mensajes que circulan entre sistemas comparten el mismo formato, y buena parte de la razón por la que el internet de hoy funciona tan bien está ahí.

Sintaxis de JSON: claves, valores, objetos, arrays

Resumamos ahora la sintaxis de forma muy breve. Las reglas de JSON son asombrosamente pocas. Conoce estas cuatro y podrás leer el 99 % de cualquier JSON.

1) Par clave-valor — la unidad más pequeña

La unidad básica es un par "nombre" y "contenido" unidos por un solo signo de dos puntos. El nombre siempre va entre comillas dobles.

"product": "Château Margaux 2020"

2) Tipos de valor — cuatro primitivos + dos estructuras

Lo que puede ir en la posición del valor está fijado:

• Cadena: texto entre comillas dobles. Ej.: "Alex"
• Número: tal cual, sin comillas. Ej.: 480000
• Booleano: true o false (sin comillas)
• Vacío: null (significa "todavía sin valor")
• Objeto: un conjunto de pares clave-valor entre llaves {}
• Array: una lista de valores entre corchetes []

3) Objeto {} — un conjunto de pares clave-valor

Une varios pares clave-valor con comas y envuélvelos en llaves: así obtienes un objeto. Una fila de Excel corresponde a uno de estos objetos.

{
  "name": "Alex",
  "email": "alex@example.com",
  "is_member": true
}

4) Array [] — una lista de la misma forma

Lista valores entre corchetes, separados por comas: eso es un array. Varias filas de Excel corresponden a uno de estos arrays.

[
  { "sku": "WINE-MARGAUX-2020", "quantity": 2 },
  { "sku": "WINE-OPUS-2019",    "quantity": 1 }
]

Y aquí está el punto realmente importante. Probablemente hayas notado que cada elemento del array de arriba es a su vez un objeto. La posición del valor puede contener otro objeto u otro array. Esa única regla recursiva es lo que le permite a JSON cargar con cualquier nivel de complejidad. La razón por la que un albarán de la tienda de vino puede expresar "un pedido con varios artículos, y cada artículo con su nombre, cantidad y precio unitario…" es justo eso.

Resumiéndolo en una frase, JSON es: "las claves y valores son la unidad básica; se pueden empaquetar en objetos y los objetos se pueden listar en arrays. Y la posición del valor puede volver a contener un objeto o un array." Todo cabe en esa frase.

Dónde aparece JSON

Fuera del albarán de la tienda de vino, JSON ya está metido a fondo en nuestra vida cotidiana. Solo que no se ve:

• Tráfico entre apps móviles y servidores: el feed de Instagram, la lista de restaurantes en una app de delivery, las cotizaciones en una app bursátil — casi todo viaja como JSON.
• Archivos de configuración: los ajustes de VS Code y muchos archivos de configuración de herramientas de desarrollo son JSON. Se elige JSON precisamente porque un humano puede abrirlos y editarlos.
• Datos públicos / abiertos: buena parte de las API de datos abiertos que publican gobiernos y organismos públicos responden en JSON.
• Integraciones SaaS y webhooks: las notificaciones que envían pasarelas de pago, servicios de envío, plataformas de mensajería y servicios de correo son, todas, un único bloque JSON.
• Salida estructurada de la IA / LLMs: pide a modelos como ChatGPT o Claude que "devuelvan el resultado como JSON" y obtendrás un formato listo para usar directamente. JSON es, además, el idioma común entre la IA y los sistemas de negocio.

No cometas el error de pensar que JSON es "un formato en el que vale cualquier cosa". Es justo lo contrario. Como destacó Chae-won en tus datos merecen un plan, JSON cobra fuerza solo cuando está clara de antemano la promesa "el JSON de este endpoint tiene estos campos". Lo libre es la sintaxis; el diseño de campos no lo es. Con tener presente esa distinción, la mayoría de los malentendidos alrededor de JSON desaparecen.

Recapitulación · Cierre de la serie

Atemos los tres bloques de una vez:

• Parte 1: Base de datos — construimos el contenedor que apila los datos del negocio con la misma forma.
• Parte 2: API — montamos la ventanilla que permite al exterior acercarse de forma segura a ese contenedor.
• Parte 3: JSON — fijamos la forma de los mensajes que cruzan esa ventanilla.

En el momento en que las tres cosas están en su sitio, tu negocio empieza a parecerse, por primera vez, a un sistema que sigue funcionando aunque tus manos se aparten. Entra un pedido en la tienda online y un bloque de JSON viaja por la ventanilla API hasta la DB; la pasarela de pago informa del resultado con otro bloque de JSON; el POS de la tienda descuenta stock con un bloque de JSON. Mientras el dueño duerme, los mensajes siguen viajando sobre el mismo acuerdo. "Automatización" es, al final, la combinación de estos tres acuerdos.

Más importante aún: una vez que tienes estos tres conceptos, cualquier término nuevo que encuentres después (GraphQL, streaming de eventos, MCP, agentes de IA…) no es más que una variación que se apoya sobre este esqueleto. Con el esqueleto en su sitio, las ramas vienen solas.

Lo que puedes probar hoy mismo

Como es el último artículo de la serie, la práctica de hoy está pensada para enlazar con las dos anteriores. Con un papel, una IA y un navegador tienes más que suficiente.

Acción 1. Escribir un evento de tu negocio como JSON

Recupera el evento que elegiste en la anterior publicación sobre API (por ejemplo: crear un pedido, registrar una reserva, recibir una consulta) y traslada cada uno de sus campos a un único bloque de JSON. Al principio puedes escribirlo plano; cuando te sientas cómodo, pliega las partes que crezcan (cliente, artículos) como un objeto dentro de otro objeto.

{
  "reservation_id": "R-2026-0001",
  "customer": {
    "name": "Alex",
    "phone": "+34-6xx-xxx-xxx"
  },
  "date": "2026-05-12",
  "party_size": 4,
  "note": "Prefiere mesa junto a la ventana"
}

Este bloque es el resultado de trasladar "un evento de mi negocio" a una forma que el sistema puede entender. Los desarrolladores arrancan exactamente desde aquí cuando esbozan una especificación de API.

Acción 2. Comprobar la sintaxis con una IA y un validador

Pega el JSON que escribiste en la Acción 1 en ChatGPT, Claude o Gemini y pídeles algo así:

Por favor comprueba si el JSON de abajo es sintácticamente válido.
Señala erratas, comillas, comas, o si las llaves y corchetes están
emparejados correctamente, y explica en palabras que entienda alguien
sin conocimientos de desarrollo qué debería corregir.

[pega aquí el JSON de la Acción 1]

Si además quieres una comprobación puramente visual, pega el mismo JSON en un validador público como JSONLint. Un "Valid JSON" en verde significa que la sintaxis está bien. Solo con repetir estos dos pasos, tu ojo para el JSON se afina muy rápido.

Acción 3. Rompe la forma en tu propio endpoint

Quienes siguieron la guía rápida de la publicación sobre API y crearon su primer endpoint en 3Min API: hoy vuelve a la página de detalle de ese endpoint y prueba dos experimentos sobre el mismo endpoint:

1. Cambia la estructura de campos — añade un campo obligatorio, o renombra uno existente; después llama al endpoint con la nueva forma de JSON y comprueba si se guarda correctamente.
2. Envía JSON roto a propósito — quita una coma, deja un campo obligatorio vacío, o pon una letra donde debería haber un número, y llama al endpoint. Lo importante es ver con tus propios ojos con qué error responde la ventanilla.

El significado de los mensajes de error que vuelven y cómo tratarlos están recogidos en la guía de resolución de problemas. En el momento en que pasas de "si sale un error, pánico" a "leer el código de error y acotar la causa", ya hablas el idioma del sistema.

👉 ¿Aún no tienes un endpoint? — guía rápida de 3 minutos

Cerrando la trilogía — ¿Hacia dónde te diriges ahora?

Llegado a este punto, tienes ya tres herramientas en la mano: el contenedor que apila los datos de tu negocio, la ventanilla que deja entrar y salir al exterior de forma segura, y la forma de los mensajes que viajan por esa ventanilla. Dentro de cada uno de estos temas hay, por supuesto, muchísimo más detalle del que hemos visto. Aun así, con lo que has entendido hasta hoy ya tienes suficiente esqueleto para extender tu negocio al ecosistema IT y, más allá, prepararte para la era de la IA. Los detalles restantes podrás ir apoyándolos sobre este esqueleto cuando la situación lo pida.

A estas alturas puede que pienses: "¿no es esto trabajo de desarrolladores?". La buena noticia es que, gracias a la IA, la frontera entre desarrollador y no desarrollador se ha vuelto mucho más borrosa que antes. Lo que te propongo no es que escribas código por tu cuenta, sino que interiorices los principios básicos de cómo se mueve la informática como una especie de intuición. Sobre esa intuición, y apoyándote en las buenas herramientas que ya existen, empezarás un ciclo: montar una API pequeña, llamarla, chocar con errores, arreglarlos. Cuando ese ciclo se acumule, llegará sola la idea: "esta parte de mi negocio también se puede automatizar". Esa sensación es precisamente el punto de partida para empujar tu negocio hacia un mercado más amplio.

Cuando el esqueleto está levantado, pasa algo divertido. Si abres las herramientas de automatización que últimamente oyes mucho — n8n, Zapier, Make — verás de un vistazo que todas funcionan sobre el mismo esqueleto: API + JSON + DB. "Añadir una fila a Google Sheets" es llamar a la API de Sheets que ofrece Google; "enviar un correo por Gmail" es llamar a la API de Gmail; "subir un archivo a Drive" es llamar a la API de Drive. Al final, estas herramientas son intermediarios que enlazan via JSON un montón de API ya públicas. Quien entiende el esqueleto usa las mismas herramientas de forma mucho más deliberada.

¿Y qué hacer ahora mismo? Mi consejo es este: si ya tienes una idea aproximada del flujo completo, aplícalo en pequeño, experimenta y choca contra las cosas. Ya habrá tiempo de pensar en un sistema propio cuando la operación crezca y la necesidad sea evidente. No ha habido en la historia un momento mejor para empezar en pequeño: la nube, las API públicas, los LLMs y las herramientas no-code están todos sosteniendo ese primer paso.

Si quieres una perspectiva más amplia sobre cómo encaja la IA con un negocio, Preparación de pequeños negocios para la IA — Datos, API y lo que debe hacer ahora es una buena continuación de lectura.

Contenedor, ventanilla, mensaje. Sobre estos tres acuerdos, tu negocio empieza a moverse incluso cuando tus manos se apartan. Gracias por haber llegado hasta el final de la trilogía.

---

← Anterior: ¿Qué es una API? Guía básica para dueños de pequeños negocios