Cómo consumir una API REST desde Excel VBA

Introducción: conectar Excel con datos externos sin copiar y pegar

Conectar Excel con servicios REST mediante VBA permite incorporar datos procedentes de otras aplicaciones y transformar respuestas JSON en tablas que se pueden consultar, analizar y actualizar. El objetivo no es convertir una hoja de cálculo en un servidor, sino eliminar una operación manual: abrir una web, descargar un archivo, copiar columnas y repetir el proceso cada semana.

Una macro puede solicitar un listado de incidencias, consultar el estado de pedidos o recoger registros de una herramienta interna; después, debe comprobar que la respuesta es válida y escribirla en una hoja concreta. La dificultad real aparece entre la petición y las celdas: cabeceras HTTP, permisos, campos ausentes, límites del servicio y protección de la información recibida.

En esta guía construiremos una consulta GET desde Excel de escritorio en Windows, leeremos una respuesta JSON con una biblioteca explícita y la convertiremos en filas. También veremos cómo añadir autenticación, enviar un POST de prueba y evitar que un fallo de red termine dañando un informe. El enfoque es práctico y delimitado: se centra en cómo programar el consumo de una API desde VBA, no en diseñar la arquitectura general de integraciones.

Índice de contenidos

Cuándo tiene sentido consumir una API desde Excel VBA

VBA resulta útil cuando el trabajo ya depende de un libro de escritorio que contiene macros, validaciones, formularios o reglas de cálculo. En lugar de pedir a una persona que descargue información y la adapte a una plantilla, una rutina puede recuperar los registros y colocarlos donde los necesita el proceso.

• Consulta de información: actualizar una hoja de seguimiento con datos que otra aplicación expone por una API autorizada.
• Preparación de informes: combinar los resultados consultados con fórmulas, gráficos o tablas dinámicas del propio libro.
• Herramientas internas: conectar botones, formularios VBA y consultas remotas para tareas de pequeña escala.
• Trabajo periódico supervisado: obtener una instantánea de información y comprobarla antes de continuar con decisiones humanas.

No conviene confundir facilidad de acceso con fiabilidad operativa. Si hay muchas personas editando simultáneamente, un gran volumen de registros, obligaciones fuertes de auditoría o actualizaciones críticas, puede ser más adecuado situar la integración en un servicio separado y utilizar Excel solo para visualizar resultados.

Para decidir cómo encaja la hoja en el conjunto de herramientas, consulta cómo integrar APIs con hojas de cálculo empresariales. Ese análisis aborda el diseño de la integración; aquí nos concentraremos en el código VBA que realiza la consulta.

Requisitos y preparación del libro de Excel

Entorno compatible

Los ejemplos utilizan Excel de escritorio para Windows y el componente COM WinHttp.WinHttpRequest.5.1. No son macros para Excel en el navegador ni un procedimiento compatible sin cambios con Excel para Mac. Excel para la Web no ejecuta VBA, y el componente WinHTTP empleado es específico de Windows.

1. Abre un libro de Excel de escritorio y guárdalo como .xlsm (libro habilitado para macros).
2. Crea una hoja llamada exactamente DatosAPI, donde se escribirán los resultados.
3. Abre el editor de Visual Basic con Alt + F11 e inserta un módulo estándar.
4. Comprueba que tu organización permite las macros de confianza y que el equipo tiene acceso HTTPS al servicio de destino.
5. Trabaja inicialmente con una API pública de pruebas; no utilices credenciales ni datos reales hasta validar el procedimiento.

Si todavía no conoces las macros, los módulos y los objetos de Excel, el artículo Introducción a VBA en Excel ofrece esa base. Aquí damos por conocidos los procedimientos Sub, las variables y las referencias a hojas y rangos.

Una biblioteca para analizar JSON

VBA no incorpora una función nativa equivalente a JSON.parse. Para los ejemplos que convierten una respuesta en registros utilizaremos VBA-JSON, cuyo módulo principal se llama JsonConverter.bas. Puedes consultar el repositorio público de VBA-JSON, revisar su licencia y obtener el módulo desde su origen.

1. En el editor VBA, selecciona Archivo > Importar archivo e incorpora JsonConverter.bas.
2. Para esta configuración en Windows, activa Herramientas > Referencias > Microsoft Scripting Runtime. La biblioteca utiliza objetos de tipo diccionario.
3. Guarda el libro y comprueba que el proyecto compila antes de ejecutar los ejemplos.

Esta dependencia no está incluida en Excel. Si no la importas, la macro que invoca JsonConverter.ParseJson no podrá compilar o ejecutarse correctamente. En una organización, cualquier módulo de terceros debe revisarse y mantenerse como parte del código del proyecto.

Realizar la primera petición GET a una API REST

Una petición GET solicita una representación de un recurso. Para probar sin autenticación usaremos https://jsonplaceholder.typicode.com/posts/1, un servicio de demostración que devuelve una publicación ficticia en JSON. Este servicio es útil para aprender; no es una fuente de datos empresariales.

Macro mínima para solicitar y examinar la respuesta

Pega el siguiente procedimiento en un módulo estándar. La referencia al componente HTTP se crea de forma tardía con CreateObject, por lo que no es necesario añadir una referencia al objeto WinHTTP en el editor.

Option Explicit

Public Sub ConsultarAPIDePrueba()
    Dim http As Object
    On Error GoTo ErrorConexion

    Set http = CreateObject("WinHttp.WinHttpRequest.5.1")
    http.SetTimeouts 5000, 5000, 10000, 15000
    http.Open "GET", "https://jsonplaceholder.typicode.com/posts/1", False
    http.SetRequestHeader "Accept", "application/json"
    http.Send

    Debug.Print "Estado HTTP: " & http.Status
    If http.Status = 200 Then
        Debug.Print Left$(http.ResponseText, 500)
    Else
        MsgBox "La API respondió con HTTP " & http.Status, vbExclamation
    End If
    Exit Sub

ErrorConexion:
    MsgBox "Error al realizar la solicitud: " & Err.Description, vbExclamation
End Sub

Ejecuta ConsultarAPIDePrueba y abre la ventana Inmediato con Ctrl + G. Allí verás el estado HTTP y parte del cuerpo devuelto. El ejemplo no modifica la hoja: su finalidad es comprobar que el equipo, Excel y el servidor pueden comunicarse.

Qué hace cada instrucción importante

• SetTimeouts fija límites de espera, en milisegundos, para resolución DNS, conexión, envío y recepción. Se configura antes de abrir la solicitud.
• Open "GET", url, False prepara una petición síncrona: Excel espera mientras se ejecuta. Por ello no debe usarse indiscriminadamente para consultas muy largas.
• SetRequestHeader "Accept", "application/json" indica el formato de respuesta deseado, aunque corresponde al servidor decidir qué entrega.
• Status permite comprobar el resultado HTTP; ResponseText entrega el cuerpo como texto.

Una respuesta HTTP 200 indica que la petición se ha atendido correctamente a nivel HTTP. No demuestra por sí sola que los registros tengan la estructura, actualidad o significado esperados. La validación del contenido es una etapa diferente.

Cómo convertir una respuesta JSON en filas y columnas de Excel

La diferencia entre consultar una API y utilizarla de verdad aparece al interpretar la respuesta. Una API puede devolver un objeto JSON, una lista de objetos o un objeto con la lista anidada bajo una propiedad. El código debe adaptarse al contrato publicado por el proveedor, no asumir que todas las respuestas tienen el mismo aspecto.

Ejemplo de estructura recibida

Para una consulta a /posts?userId=1, el servicio de pruebas responde con una lista de publicaciones. Simplificando su contenido, cada elemento tiene este esquema:

[
  {
    "userId": 1,
    "id": 1,
    "title": "Título de ejemplo",
    "body": "Contenido de ejemplo"
  }
]

El destino será la hoja DatosAPI, con tres columnas: ID, Título y Texto. La propiedad userId existe en el origen, pero no la necesitamos en este ejemplo. Seleccionar las columnas necesarias evita trasladar campos sin una finalidad definida.

Macro completa para importar los registros

El siguiente procedimiento realiza la solicitud, comprueba el estado, convierte el JSON mediante JsonConverter, prepara una matriz en memoria y finalmente escribe todas las filas de una sola vez. Antes de ejecutarlo deben existir la hoja DatosAPI y el módulo JsonConverter.bas. Si pegas ambos ejemplos en el mismo módulo, conserva Option Explicit una sola vez, al principio.

Public Sub ImportarPublicacionesAPI()
    Dim http As Object
    Dim publicaciones As Object
    Dim registro As Variant
    Dim datos() As Variant
    Dim ws As Worksheet
    Dim i As Long
    Dim ultimaFila As Long

    On Error GoTo Fallo

    Set http = CreateObject("WinHttp.WinHttpRequest.5.1")
    http.SetTimeouts 5000, 5000, 10000, 15000
    http.Open "GET", _
        "https://jsonplaceholder.typicode.com/posts?userId=1", False
    http.SetRequestHeader "Accept", "application/json"
    http.Send

    If http.Status <> 200 Then
        Err.Raise vbObjectError + 1001, , _
            "La API devolvió HTTP " & http.Status
    End If

    Set publicaciones = JsonConverter.ParseJson(http.ResponseText)
    If TypeName(publicaciones) <> "Collection" Then
        Err.Raise vbObjectError + 1002, , _
            "Se esperaba una lista JSON de publicaciones"
    End If

    If publicaciones.Count > 0 Then
        ReDim datos(1 To publicaciones.Count, 1 To 3)
        i = 0
        For Each registro In publicaciones
            If Not registro.Exists("id") Or _
               Not registro.Exists("title") Or _
               Not registro.Exists("body") Then
                Err.Raise vbObjectError + 1003, , _
                    "Hay una publicación sin campos obligatorios"
            End If

            i = i + 1
            datos(i, 1) = CLng(registro("id"))
            datos(i, 2) = CStr(registro("title"))
            datos(i, 3) = CStr(registro("body"))
        Next registro
    End If

    Set ws = ThisWorkbook.Worksheets("DatosAPI")
    ultimaFila = ws.Cells(ws.Rows.Count, "A").End(xlUp).Row

    ws.Range("A1:C1").Value = Array("ID", "Título", "Texto")
    If ultimaFila >= 2 Then
        ws.Range("A2:C" & ultimaFila).ClearContents
    End If

    If publicaciones.Count > 0 Then
        ws.Range("B2:C" & (publicaciones.Count + 1)).NumberFormat = "@"
        ws.Range("A2").Resize(publicaciones.Count, 3).Value2 = datos
    End If

    ws.Columns("A:C").AutoFit
    MsgBox "Importados: " & publicaciones.Count & " registros", _
           vbInformation
    Exit Sub

Fallo:
    MsgBox "Importación no completada: " & Err.Description, _
           vbExclamation
End Sub

El código comprueba y prepara los datos antes de borrar el resultado anterior. Así, si falla la conexión, el estado HTTP o el análisis JSON, no se sobrescribe la tabla. Se trata de una precaución básica, no de una transacción: si ocurre un fallo durante la escritura en Excel, puede quedar una actualización parcial. Para informes críticos conviene escribir primero en una hoja temporal, validar y sustituir después el resultado.

La matriz datos evita escribir celda por celda, una operación que puede ralentizar considerablemente una macro. Además, la macro utiliza ThisWorkbook para señalar el libro que contiene el código, en lugar de depender del archivo que esté activo cuando se ejecute.

Adaptación a una API cuyo JSON empieza por un objeto

Algunos servicios devuelven algo como {"resultados": [...]} en lugar de un array en la raíz. En ese caso, primero se analiza el objeto y después se selecciona la colección indicada por el contrato:

Dim raiz As Object
Dim elementos As Object

Set raiz = JsonConverter.ParseJson(http.ResponseText)
If Not raiz.Exists("resultados") Then
    Err.Raise vbObjectError + 1010, , "Falta la propiedad resultados"
End If
Set elementos = raiz("resultados")  ' Se espera una lista JSON

No copies el nombre resultados sin comprobar la respuesta de la API real. También hay que comprobar si existen campos opcionales o valores null: una conversión directa con CStr puede fallar si recibe Null. El ejemplo principal utiliza un servicio de prueba con las propiedades esperadas.

Cómo añadir autenticación y cabeceras HTTP en VBA

Muchas APIs corporativas no permiten consultas anónimas. Según el proveedor, pueden solicitar una API Key, un token Bearer, OAuth 2.0 u otro mecanismo. El nombre de la cabecera y el alcance de los permisos deben obtenerse de la documentación del servicio.

Enviar un token Bearer

Cuando la API requiere un token Bearer ya obtenido de forma legítima, la cabecera HTTP adopta esta estructura:

' token se obtiene antes mediante el mecanismo autorizado.
' http es el objeto WinHttpRequest ya abierto.
http.SetRequestHeader "Authorization", "Bearer " & token
http.SetRequestHeader "Accept", "application/json"
http.Send

Este fragmento se inserta después de Open y antes de Send. La variable token representa un valor obtenido previamente mediante el mecanismo autorizado de tu organización; no es una invitación a escribirlo dentro del módulo o guardarlo en una celda visible.

Una API Key podría enviarse, por ejemplo, en una cabecera X-API-Key si así lo exige el proveedor. Otras APIs solicitan parámetros o cabeceras distintas; no existe una regla universal. Puedes profundizar en autenticación mediante API Key y en uso de tokens Bearer para acceder a una API.

Por qué no basta con recibir un código 401 o 403

Un 401 puede significar que no se han proporcionado credenciales válidas. Un 403 suele indicar que la identidad reconocida no tiene permiso para la operación. No conviene corregir ambos casos probando claves al azar ni aumentando los permisos sin conocer el alcance requerido. Comprueba qué identidad ejecuta la petición, a qué recurso accede y qué permisos se le han concedido.

Cómo enviar datos JSON con POST desde Excel VBA

Consultar registros es una operación distinta de crear o modificar información. Para enviar contenido, una API puede permitir POST, PUT o PATCH, pero sus significados, permisos y consecuencias dependen del contrato. Antes de automatizar escrituras, es preferible practicar con un entorno de pruebas y datos no sensibles.

Este ejemplo utiliza el método ConvertToJson de la misma biblioteca VBA-JSON y envía una publicación ficticia a JSONPlaceholder:

Public Sub EnviarPublicacionDePrueba()
    Dim http As Object
    Dim payload As Object
    On Error GoTo Fallo

    Set payload = CreateObject("Scripting.Dictionary")
    payload.Add "title", "Prueba de integracion"
    payload.Add "body", "Contenido ficticio"
    payload.Add "userId", 1

    Set http = CreateObject("WinHttp.WinHttpRequest.5.1")
    http.SetTimeouts 5000, 5000, 10000, 15000
    http.Open "POST", "https://jsonplaceholder.typicode.com/posts", False
    http.SetRequestHeader "Accept", "application/json"
    http.SetRequestHeader "Content-Type", "application/json; charset=utf-8"
    http.Send JsonConverter.ConvertToJson(payload)

    Debug.Print "HTTP " & http.Status
    Debug.Print Left$(http.ResponseText, 400)
    If http.Status <> 201 Then
        MsgBox "Respuesta no esperada: HTTP " & http.Status, vbExclamation
    End If
    Exit Sub

Fallo:
    MsgBox "No se pudo completar la prueba: " & Err.Description, _
           vbExclamation
End Sub

JSONPlaceholder simula el resultado y suele devolver 201 Created, pero no guarda realmente esa publicación. En una API de producción no se debe interpretar cualquier 201 como prueba de que la información ya aparece en todos los sistemas relacionados: pueden existir procesos asíncronos y verificaciones adicionales.

Para trabajar correctamente con cuerpos JSON, valores opcionales y cabeceras Content-Type, consulta también cómo enviar datos JSON correctamente a una API. Ese tema requiere especial atención cuando los campos contienen fechas, importes o caracteres no ASCII.

Paginación, límites y rendimiento cuando crece el volumen de datos

No asumir que la primera respuesta contiene todo

Una consulta que devuelve diez filas puede parecer completa, aunque el servidor tenga miles. Muchas APIs paginan sus resultados mediante parámetros como page y limit, un cursor o un enlace de continuación. La forma de avanzar entre páginas es específica de cada API: hay que seguir la documentación y no inventar nombres de parámetros.

Para una importación paginada fiable, la macro debería acumular las páginas en memoria o en un destino temporal, llevar una cuenta de registros, detectar el final según las reglas del proveedor y rechazar bucles que devuelvan continuamente la misma página. Una importación interrumpida no debería presentarse como un conjunto de datos completo.

Leer menos y escribir mejor

• Solicita solo los campos y registros necesarios cuando la API admita filtros.
• Evita escribir celda por celda: transfiere matrices completas a rangos.
• Conserva identificadores únicos como texto si podrían exceder la precisión numérica de Excel o contener ceros iniciales.
• Define una política para duplicados y para registros desaparecidos entre dos consultas.
• Si vas a refrescar con frecuencia, respeta los límites de peticiones y evita descargar todo el histórico cada vez.
• No confundas una demora de Excel con una demora de red: mide cada etapa por separado.

Si una API limita cuántas llamadas pueden realizarse, una actualización masiva debe planificarse con esos límites. Para ese aspecto operativo, consulta cómo controlar límites de uso y cuotas de una API. Para respuestas más complejas, puede resultar útil trabajar con respuestas JSON desde distintos lenguajes, sin perder de vista las particularidades de VBA.

Controlar errores, tiempos de espera y resultados incompletos

Cuando la macro consume una API, se combinan dos clases de fallo: los de transporte o ejecución local y los que el servidor expresa mediante una respuesta HTTP. Un control de errores sólido debe distinguirlos. La estructura On Error GoTo captura fallos de ejecución de VBA o del objeto COM; la propiedad Status debe comprobarse cuando el servidor sí ha respondido.

Estados HTTP que conviene reconocer

Los códigos ayudan a orientar el diagnóstico, pero no sustituyen la documentación. Un fallo DNS, TLS, de conexión o de tiempo de espera puede impedir obtener cualquier estado HTTP. En ese caso, Err.Description ofrece una pista local, aunque no debe usarse como identificador estable de errores para automatizar decisiones.

Qué registrar sin copiar datos sensibles

Para una macro periódica, es útil anotar fecha de intento, operación, recurso lógico consultado, resultado, código HTTP si lo hubo, número de filas importadas y duración aproximada. Evita escribir tokens, cabeceras de autorización, respuestas completas y datos personales en una hoja de incidencias. Para un diagnóstico más sistemático, consulta cómo detectar errores habituales al consumir APIs y cómo registrar llamadas a una API.

Precaución con los reintentos

Repetir una lectura GET tras un fallo transitorio puede ser razonable, siempre con un límite y una espera adecuados. Repetir automáticamente un POST porque venció el tiempo de respuesta es más delicado: el servidor podría haber procesado la operación aunque Excel no recibiera la confirmación. Si una API permite claves de idempotencia o consultas de conciliación, utilízalas conforme a su contrato.

Seguridad práctica al conectar Excel VBA con APIs corporativas

Una macro que consulta datos externos amplía la superficie de exposición del libro. El riesgo no desaparece por tratarse de un archivo .xlsm utilizado por una sola persona. La protección debe abarcar las credenciales, el destino de la petición, el contenido recibido y la forma de distribuir el archivo.

• Protege las credenciales: no incrustes claves o tokens permanentes en código, celdas, nombres definidos ni archivos compartidos. El proyecto VBA protegido con contraseña no constituye un almacén seguro de secretos.
• Usa HTTPS y valida el servidor: no desactives verificaciones de certificados para solucionar un fallo de conexión.
• Aplica permisos mínimos: una macro de solo lectura no necesita credenciales capaces de borrar o modificar registros.
• Controla qué endpoints se pueden consultar: evita aceptar sin validación URLs completas procedentes de celdas manipulables por terceros.
• Trata el JSON como datos no confiables: verifica tipos, tamaños y campos antes de insertarlos; presta atención a cadenas que podrían interpretarse como fórmulas al exportar o reintroducirlas en hojas.
• Limita la distribución: si el libro contiene datos de clientes, una exportación automática puede multiplicar copias que luego nadie controla.
• Firma o distribuye las macros de forma controlada: no aconsejes a los usuarios desactivar globalmente la seguridad de Office para que el archivo funcione.

Una API puede funcionar perfectamente desde VBA y, aun así, ser una mala elección si obliga a guardar un secreto compartido dentro del libro. En ese escenario es preferible interponer un servicio controlado que gestione las credenciales y entregue únicamente los datos autorizados a cada usuario.

Excel VBA frente a Power Query, Office Scripts y un proceso externo

No todas las conexiones desde Excel necesitan VBA. La tecnología adecuada depende de si la tarea es principalmente consultar y transformar, interactuar con el libro o ejecutar integraciones fuera de la sesión del usuario.

Para una actualización sencilla de datos, prueba primero si Power Query resuelve la necesidad. Utiliza VBA cuando la interacción con el propio libro sea decisiva. Y, si el resultado debe llegar puntualmente todos los días aunque ningún usuario abra Excel, estudia ejecutar la consulta fuera del archivo y consumir después los datos ya preparados.

Caso práctico: actualizar un informe operativo sin perder la versión anterior

Imagina un pequeño equipo que consulta cada mañana el estado de tareas de un sistema externo y utiliza Excel para clasificar prioridades y preparar un resumen. Antes, una persona abría una web, aplicaba filtros y copiaba los registros uno por uno. Ahora se plantea usar una API autorizada.

1. Definir el resultado: una hoja DatosAPI con identificador, asunto y descripción, más otra hoja que contiene cálculos propios del equipo.
2. Verificar el contrato: confirmar endpoint, parámetros, autenticación, paginación y formato de respuesta.
3. Consultar sin tocar el informe: realizar la petición, comprobar el estado y analizar el JSON.
4. Validar: verificar claves necesarias, número razonable de filas y ausencia de errores de estructura.
5. Actualizar de una vez: reemplazar únicamente el área de datos importados; no las fórmulas y anotaciones del equipo.
6. Dejar evidencia: registrar el momento de la última importación completa y avisar si se ha conservado una versión anterior por un fallo.

La diferencia operativa importante no consiste en haber eliminado cinco minutos de copia y pega, sino en saber qué significa el número mostrado en la hoja. Si el servidor falla, el informe no debe sugerir que contiene información actual. Mostrar de forma visible la fecha y el estado de la última actualización es tan importante como la propia macro.

Cuando el libro deja de ser un apoyo individual y empieza a alimentar decisiones de varias áreas, conviene revisar además quién es responsable de los datos, qué cambios pueden producirse en el origen y cómo se documenta la integración. Ese trabajo amplía lo explicado aquí, pero no puede reemplazarse por unas líneas adicionales de VBA.

Preguntas frecuentes sobre consumir APIs REST desde Excel VBA

Conclusión: una consulta útil es la que entrega datos fiables a Excel

Consumir una API REST desde Excel VBA requiere encadenar varias responsabilidades: construir una solicitud HTTP, interpretar su respuesta, comprobar errores, transformar JSON y actualizar un rango sin romper el trabajo existente. Un ejemplo de diez líneas puede demostrar la conexión; una solución utilizada de verdad necesita además control de credenciales, validación y un comportamiento definido cuando algo falla.

Empieza por una consulta de solo lectura, con una respuesta conocida y una hoja de destino aislada. Después añade autenticación, tratamiento de campos opcionales y soporte para el volumen real. El objetivo no es que Excel haga todas las integraciones posibles, sino utilizar VBA cuando aporta una mejora concreta, comprensible y mantenible al trabajo diario.