Cómo enviar datos JSON correctamente a una API

Introducción: enviar JSON no consiste solo en hacer un POST

JSON, API, validación, integridad y trazabilidad son cinco conceptos que conviene dominar cuando una aplicación necesita transmitir información a otra. Un envío aparentemente sencillo puede terminar creando registros incompletos, duplicando operaciones o comunicando datos que el sistema receptor no sabe interpretar.

Imagina una microempresa que registra solicitudes desde una web y necesita trasladarlas a una aplicación de gestión. El objetivo no es simplemente que el servidor responda: es que reciba el cliente correcto, reconozca cada campo, aplique las reglas del negocio y confirme qué ha hecho con la información.

Esta guía explica cómo enviar datos JSON correctamente a una API HTTP, desde el diseño del cuerpo de la petición hasta las comprobaciones posteriores. Incluye ejemplos reproducibles con curl y Python, errores frecuentes y un procedimiento práctico para pasar de una prueba manual a una integración fiable. Los ejemplos utilizan una dirección ficticia: debes sustituirla por la URL y el contrato de tu API.

Índice de contenidos

Qué significa enviar JSON a una API

JSON (JavaScript Object Notation) es un formato de texto estructurado con el que se representan objetos, listas y valores. En una API HTTP es habitual utilizarlo como cuerpo de una solicitud para crear o actualizar información. No es una base de datos ni un lenguaje de programación: es una forma acordada de representar datos.

Una solicitud tiene varias piezas que deben encajar: el endpoint de destino, el método HTTP, las cabeceras, el cuerpo JSON y, cuando se exige, las credenciales de acceso. La respuesta posterior informa del resultado mediante un código de estado y, en ocasiones, otro documento JSON.

Supongamos que un sistema recibe altas de contactos en https://api.ejemplo.com/v1/contactos. La API podría admitir este objeto:

{
  "referencia_externa": "WEB-2026-0042",
  "nombre": "Laura Martín",
  "correo": "laura@example.com",
  "activo": true,
  "etiquetas": ["cliente", "web"]
}

El ejemplo contiene cadenas, un booleano y una lista. Su estructura es válida como JSON, pero eso no garantiza que la API lo acepte: el servidor podría exigir otros nombres de campo, formatos, permisos o propiedades obligatorias. La especificación de esa API —su contrato— siempre tiene prioridad sobre un ejemplo genérico.

Conviene distinguir esta tarea de procesar respuestas JSON recibidas desde una API: allí el foco está en interpretar datos entrantes; aquí, en construir y enviar información saliente sin errores.

Cómo preparar un cuerpo JSON válido y coherente

Respeta los tipos de datos y los nombres de los campos

JSON distingue entre cadenas ("texto"), números (125.50), booleanos (true y false), null, objetos ({}) y listas ([]). Una cifra entre comillas es una cadena, no un número. Una fecha suele viajar como cadena con el formato indicado por la API, por ejemplo "2026-10-24".

Hay cuatro fallos muy habituales: escribir True en lugar de true, dejar una coma al final de una lista, utilizar comillas simples para delimitar cadenas JSON y cambiar la capitalización de un nombre de campo. Los nombres suelen ser sensibles a mayúsculas y minúsculas.

No confundas campo ausente, null y valor vacío

Estos tres mensajes pueden tener efectos distintos:

{"telefono": null}
{"telefono": ""}
{}

El primero incluye el campo con valor nulo, el segundo incluye una cadena vacía y el tercero omite el campo. En una actualización parcial, algunos servicios interpretan la omisión como «no modificar» y el nulo como «borrar»; otros tienen reglas diferentes. No presupongas el comportamiento: compruébalo en la documentación y en pruebas controladas.

Prepara los importes y los identificadores con cuidado

Un identificador como "00152" normalmente debe tratarse como texto para conservar sus ceros iniciales. Los importes monetarios requieren especial atención: la representación recomendada puede ser en unidades mínimas enteras (por ejemplo, céntimos) o en cadenas decimales, según el contrato. Evita redondeos involuntarios si trabajas con dinero.

También es importante utilizar una codificación coherente, normalmente UTF-8, para conservar nombres, acentos y otros caracteres internacionales. No fabriques JSON concatenando fragmentos de texto: utiliza las funciones de serialización de tu lenguaje.

Elegir el método HTTP, la dirección y las cabeceras

Los métodos más habituales cuando se transmiten datos son POST, PUT y PATCH, pero no son intercambiables. POST suele solicitar la creación de un recurso o la ejecución de una operación; PUT suele establecer o sustituir el estado de un recurso identificado; y PATCH solicita una modificación parcial. El comportamiento exacto depende de la API.

La cabecera Content-Type: application/json es especialmente importante. No basta con incluir llaves y comillas en el cuerpo: el receptor necesita saber cómo interpretarlo. Accept expresa una preferencia de respuesta, pero no obliga al servidor a devolver JSON en todos los casos.

La autenticación merece su propio estudio. Según el servicio, pueden exigirse claves o tokens; consulta los contenidos específicos sobre autenticación con API Key y uso de tokens Bearer para profundizar en esas alternativas sin mezclar credenciales con los datos del negocio.

Cómo enviar un JSON a una API con curl

curl permite inspeccionar una petición HTTP sin crear una aplicación completa. Es útil para comprobar rápidamente si el problema está en el cuerpo JSON, en las cabeceras o en el código que después integrará la API. Este ejemplo presupone que el endpoint admite POST y no necesita autenticación; en un servicio real debes añadir la credencial que corresponda.

1. Guarda el contenido en un fichero

Crea un archivo llamado contacto.json en UTF-8:

{
  "referencia_externa": "WEB-2026-0042",
  "nombre": "Laura Martín",
  "correo": "laura@example.com",
  "activo": true,
  "etiquetas": ["cliente", "web"]
}

2. Envía la solicitud

curl --fail-with-body --show-error \
  --request POST \
  'https://api.ejemplo.com/v1/contactos' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary '@contacto.json'

--data-binary @contacto.json envía los bytes del archivo sin transformar sus saltos de línea; --request POST explicita el método. --fail-with-body hace que curl devuelva un código de salida de error ante respuestas HTTP 400 o superiores y conserve el cuerpo recibido para analizarlo. Esta opción requiere una versión de curl que la admita. Recuerda que api.ejemplo.com es un dominio ilustrativo, no un servicio al que enviar información real.

3. Comprueba el código de estado además del contenido

curl --silent --show-error \
  --output respuesta.json \
  --write-out 'HTTP %{http_code}\n' \
  --request POST \
  'https://api.ejemplo.com/v1/contactos' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary '@contacto.json'

Así separas el cuerpo recibido (respuesta.json) del estado HTTP. Para depurar las cabeceras puedes utilizar --include, pero evita compartir trazas que contengan tokens o datos personales.

Cómo enviar JSON desde Python sin construir el texto a mano

En Python, la biblioteca requests simplifica la serialización de objetos y el manejo básico de respuestas. Primero hay que instalarla en el entorno correspondiente mediante python -m pip install requests.

import os
import requests

url = "https://api.ejemplo.com/v1/contactos"
payload = {
    "referencia_externa": "WEB-2026-0042",
    "nombre": "Laura Martín",
    "correo": "laura@example.com",
    "activo": True,
    "etiquetas": ["cliente", "web"],
}

headers = {"Accept": "application/json"}
token = os.environ.get("API_TOKEN")
if token:
    headers["Authorization"] = f"Bearer {token}"

try:
    respuesta = requests.post(
        url,
        json=payload,
        headers=headers,
        timeout=(5, 20),
    )
    print("Estado HTTP:", respuesta.status_code)
    respuesta.raise_for_status()

    if respuesta.content:
        try:
            print("Respuesta JSON:", respuesta.json())
        except requests.exceptions.JSONDecodeError:
            print("Respuesta no JSON (o JSON inválido)")
    else:
        print("La respuesta no contiene cuerpo")

except requests.exceptions.Timeout:
    print("Tiempo de espera agotado: resultado remoto no confirmado")
except requests.exceptions.HTTPError as error:
    print("La API ha rechazado la petición:", error)
except requests.exceptions.RequestException as error:
    print("Fallo de comunicación:", error)

La opción json=payload serializa el diccionario y establece automáticamente el Content-Type: application/json, salvo que se configure una cabecera que lo sustituya. Esto es diferente de data=payload, que no equivale a enviar el mismo objeto como JSON. El valor de timeout=(5, 20) fija un límite de conexión y otro de lectura: no debe interpretarse como garantía de duración máxima total.

La variable de entorno API_TOKEN se utiliza solo si el servicio requiere ese tipo de credencial; para un servicio autenticado, la aplicación debe fallar de forma controlada si no se ha configurado el token, en vez de continuar como si la llamada estuviera autorizada.

Detalle decisivo: un fallo de red o un timeout no demuestra que la operación no se haya ejecutado. El servidor podría haber creado el registro antes de perderse la respuesta. Por eso no conviene repetir indiscriminadamente un POST.

Validar JSON antes de transmitirlo: sintaxis y reglas de negocio

Una cadena JSON puede ser sintácticamente correcta y, aun así, no ser válida para una aplicación concreta. Conviene establecer dos niveles de comprobación: validación del formato y validación de las reglas del servicio.

Validación sintáctica

Si tienes un archivo local, puedes comprobarlo desde Python sin transmitirlo:

python -m json.tool contacto.json

El comando informa si el contenido no puede interpretarse como JSON. También ayuda a detectar llaves o comillas mal cerradas. Sin embargo, no verifica si existen los campos exigidos por el servidor.

Validación del contenido

Antes del envío revisa, como mínimo, si están presentes los campos obligatorios, si cada valor tiene el tipo previsto, si el correo y las fechas cumplen el formato requerido, si los identificadores existen, si las longitudes están dentro de los límites y si se están enviando propiedades prohibidas.

Algunas APIs publican esquemas JSON Schema u OpenAPI. Cuando estén disponibles, úsalos para generar validaciones y pruebas coherentes con el contrato. Las reglas de negocio del servidor siguen siendo autoritativas: superar una validación local no implica que una operación tenga que ser aceptada.

Cuando los datos proceden de formularios u hojas de cálculo, es útil aplicar previamente los criterios descritos en cómo mejorar la calidad de los datos antes de automatizar procesos.

Interpretar la respuesta de la API y evitar operaciones duplicadas

Lee los códigos HTTP en su contexto

Los códigos HTTP orientan, pero no sustituyen la documentación de la API. Un 200 tampoco asegura por sí solo que se haya persistido exactamente el contenido esperado: revisa los identificadores, el resultado funcional y, cuando sea necesario, consulta posteriormente el recurso.

Diseña reintentos sin crear registros duplicados

Los reintentos automáticos son adecuados para algunos fallos transitorios, pero necesitan límites, pausas progresivas y una política explícita. En particular, un POST puede producir un efecto nuevo cada vez que se repite. Si el servidor lo permite, emplea una clave de idempotencia estable por operación, con la cabecera y la semántica documentadas por esa API. Otra alternativa, según el servicio, es utilizar un identificador externo único y comprobar si la operación ya existe.

Por ejemplo, si una solicitud web se identifica como WEB-2026-0042, la integración puede registrar localmente qué envío corresponde a esa referencia, qué respuesta se obtuvo y si el proceso terminó. No supongas que incluir el campo referencia_externa evita duplicados: el servidor debe imponer esa regla o proporcionar un mecanismo equivalente.

Para profundizar en fallos de integración y códigos de respuesta, consulta cómo detectar errores habituales al consumir APIs; si tu problema está relacionado con restricciones de frecuencia, resulta pertinente cómo controlar los límites de uso y cuotas de una API.

Enviar datos JSON de forma segura

El JSON no cifra ni protege los datos por sí mismo. Cuando se transmite información de clientes, pedidos o procesos internos, la protección debe abarcar tanto el transporte como las credenciales, los permisos y la trazabilidad.

• Utiliza HTTPS y verifica los certificados; no desactives su validación para solucionar errores de conexión.
• Mantén las credenciales fuera del código fuente, especialmente si se comparte o versiona. Emplea almacenes de secretos o variables de entorno gestionadas con permisos adecuados.
• Envía solo los campos necesarios. Una API no necesita recibir información personal adicional por comodidad.
• No registres cuerpos completos por defecto cuando puedan contener datos personales, secretos o información empresarial sensible. Aplica enmascaramiento y plazos de conservación.
• Comprueba el destino real para evitar enviar datos de producción a servidores de prueba o a direcciones equivocadas.
• Limita permisos y controla los accesos según la operación que deba realizar la integración.

Si trabajas con varios sistemas internos, la protección del intercambio debe coordinarse con los criterios generales de seguridad al compartir datos entre aplicaciones.

Procedimiento de comprobación antes de utilizar un envío JSON en producción

Una integración no está lista solo porque una prueba haya devuelto 201 Created. El paso a producción exige poder explicar qué se ha enviado, por qué, cómo se ha validado y qué ocurre si la comunicación falla a mitad del proceso.

1. Confirma el contrato: endpoint, versión, método, esquema, campos obligatorios, permisos y posibles respuestas.
2. Prepara datos de prueba: utiliza identificadores y direcciones ficticias, además de casos límite documentados.
3. Valida antes de enviar: comprueba sintaxis JSON, tipos, formatos, valores permitidos y reglas de negocio disponibles.
4. Prueba el caso correcto y varios incorrectos: falta de campo obligatorio, credencial inválida, valor duplicado y agotamiento de tiempo de espera.
5. Verifica el efecto remoto: comprueba que el registro o la operación resultante coincide con lo esperado, no únicamente el estado HTTP.
6. Define los reintentos: determina qué solicitudes pueden repetirse y cómo se impedirá la duplicación de operaciones.
7. Implanta observabilidad proporcional: guarda hora, destino lógico, referencia de operación, duración, estado y un identificador de correlación cuando exista, sin exponer secretos.
8. Documenta cambios: conserva ejemplos de solicitudes y respuestas anonimizadas, versión de contrato y procedimiento de recuperación.

Para mantener un histórico útil de solicitudes sin almacenar información innecesaria, puedes ampliar estas prácticas con cómo registrar llamadas realizadas a una API. Cuando la lógica de envío se reutiliza en distintos procesos, conviene además centralizar la configuración y el manejo de errores, como se explica en scripts reutilizables para consumir múltiples APIs.

Ejemplo de una incidencia que parece pequeña

Una persona pulsa «Guardar cliente» y la aplicación envía el JSON. El servidor crea el contacto, pero la conexión se corta antes de que llegue la respuesta. El operador vuelve a pulsar y aparece un duplicado. El problema no era la sintaxis del JSON: faltaba una regla para reconocer que ambas peticiones representaban una misma operación de negocio. Este tipo de fallo explica por qué la comprobación posterior y la idempotencia deben diseñarse desde el principio.

Preguntas frecuentes sobre el envío de JSON a APIs

Conclusión: el envío correcto termina cuando el resultado está comprobado

Enviar JSON correctamente a una API exige más que formar un objeto con llaves y comillas. La calidad de una integración depende de respetar el contrato, escoger el método apropiado, declarar el tipo de contenido, validar los valores, proteger la comunicación y comprender los resultados.

Para un profesional que automatiza operaciones de una empresa pequeña, la ventaja práctica es clara: menos correcciones manuales, menos duplicidades y una comunicación más previsible entre aplicaciones. Empieza por una petición mínima que puedas verificar y añade controles a medida que la operación gane importancia.

El objetivo no es conseguir que «la API responda», sino poder demostrar qué información recibió, qué operación realizó y cómo recuperarte si algo falla.